ktstr/scenario/
payload_run.rs

1//! Runtime builder for launching a [`Payload`] from a test body.
2//!
3//! `ctx.payload(&X)` returns a [`PayloadRun`] whose chainable
4//! methods configure args, checks, and cgroup placement before the
5//! terminal `.run()` (foreground) or `.spawn()` (background)
6//! executes the binary inside the guest VM.
7//!
8//! `.run()` blocks until the child exits and returns
9//! `Result<(AssertResult, PayloadMetrics)>`. The builder is a pure
10//! guest-side std::process::Child wrapper — no cross-VM proxy.
11//!
12//! `PayloadKind::Scheduler` payloads are rejected at `.run()`:
13//! schedulers are launched by the framework at test start, not by
14//! test-body invocation. Only `PayloadKind::Binary` payloads are
15//! runnable via this builder.
16//!
17//! Args composition:
18//! 1. `payload.default_args` unless `.clear_args()` was called.
19//! 2. Plus any runtime `.arg(...)` / `.args(...)` appends.
20//!
21//! Checks composition is identical in shape.
22//!
23//! # Stdout-primary, stderr-fallback metric extraction
24//!
25//! The extraction pipeline runs `extract_metrics`
26//! against **stdout first**. When that returns an empty metric set
27//! AND stderr is non-empty, the extractor retries against stderr.
28//! This preserves the stdout-primary contract for well-behaved
29//! binaries (noisy stderr never corrupts the metric stream) while
30//! still handling payloads that emit their structured output only on
31//! stderr — e.g. schbench's default percentile tables via
32//! `show_latencies` → `fprintf(stderr, ...)`. The two streams are
33//! never merged: concurrent drain threads for stdout/stderr provide
34//! no ordering guarantee, so interleaving would corrupt any document
35//! whose bytes span both streams.
36//!
37//! Stderr is still forwarded verbatim into the exit-code-mismatch
38//! detail produced by [`MetricCheck::ExitCodeEq`] (see the
39//! `format_exit_mismatch` path) so failing binaries surface their
40//! error output directly.
41
42use std::borrow::Cow;
43use std::path::PathBuf;
44use std::sync::OnceLock;
45use std::sync::atomic::{AtomicUsize, Ordering};
46use std::thread::ThreadId;
47
48use std::time::Duration;
49
50use anyhow::{Context, Result, anyhow};
51
52use crate::assert::{AssertDetail, AssertResult, DetailKind};
53use crate::scenario::Ctx;
54use crate::test_support::{
55    Metric, MetricCheck, Payload, PayloadKind, PayloadMetrics, extract_metrics,
56};
57
58/// Per-process monotonic counter for payload-invocation indexing.
59///
60/// Increments once per `.run()` / `.wait()` / `.kill()` /
61/// `.try_wait()` terminal call (whichever produces the
62/// [`crate::test_support::PayloadMetrics`] emission). Each guest VM is a fresh process, so
63/// the counter starts at 0 every test boot. Stamped onto
64/// [`PayloadMetrics::payload_index`] so the host preserves
65/// per-invocation identity independent of SHM emission order.
66///
67/// `Ordering::Relaxed` is sufficient: the counter's only consumer
68/// is the same thread that incremented (the emit happens inside
69/// the calling thread's `.run()` / `.wait()` / etc.), and the only
70/// invariant required is "every call returns a unique value." A
71/// future multi-thread caller would need `Ordering::SeqCst` only
72/// if it wanted total ordering; `fetch_add(1, Relaxed)` already
73/// guarantees unique values across threads.
74static PAYLOAD_INVOCATION_COUNTER: AtomicUsize = AtomicUsize::new(0);
75
76/// Allocate the next per-invocation index. See
77/// [`PAYLOAD_INVOCATION_COUNTER`] for the lifecycle and ordering
78/// rationale.
79fn next_payload_index() -> usize {
80    PAYLOAD_INVOCATION_COUNTER.fetch_add(1, Ordering::Relaxed)
81}
82
83/// Builder returned by [`Ctx::payload`](crate::scenario::Ctx).
84///
85/// Configure the run via chainable methods, then invoke `.run()`
86/// (foreground, blocking) or `.spawn()` (background) to execute the
87/// payload's binary inside the guest VM and receive the extracted
88/// [`crate::test_support::PayloadMetrics`] plus an [`AssertResult`] for any declared
89/// [`MetricCheck`]s.
90pub struct PayloadRun<'a> {
91    ctx: &'a Ctx<'a>,
92    payload: &'static Payload,
93    /// Effective argv. Initialized to `payload.default_args` on
94    /// construction; `.arg`/`.args` append, `.clear_args` truncates.
95    args: Vec<String>,
96    /// Effective check list. Initialized to `payload.default_checks`;
97    /// `.check` appends, `.clear_checks` truncates.
98    checks: Vec<MetricCheck>,
99    /// User-supplied relative cgroup name (from the `in_cgroup` arg). The
100    /// absolute path is resolved + validated at `.run()`/`.spawn()`.
101    /// [`Cow`] keeps static-name callers zero-alloc while still
102    /// accepting owned Strings from dynamic call sites.
103    cgroup: Option<Cow<'static, str>>,
104    /// Optional runtime bound for the foreground `.run()` path. `None`
105    /// means wait indefinitely; `Some(duration)` arms a deadline
106    /// watchdog that SIGKILLs the payload's process group if it has
107    /// not exited by the deadline. Set via [`timeout`](Self::timeout).
108    /// Ignored by `.spawn()` — background handles manage their own
109    /// lifetime via [`PayloadHandle::wait`] / `.kill()` / `.try_wait()`.
110    timeout: Option<Duration>,
111}
112
113impl std::fmt::Debug for PayloadRun<'_> {
114    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
115        f.debug_struct("PayloadRun")
116            .field("payload", &self.payload.name)
117            .field("args_len", &self.args.len())
118            .field("checks_len", &self.checks.len())
119            .field("cgroup", &self.cgroup)
120            .field("timeout", &self.timeout)
121            .finish()
122    }
123}
124
125impl<'a> PayloadRun<'a> {
126    pub(crate) fn new(ctx: &'a Ctx<'a>, payload: &'static Payload) -> Self {
127        let args = payload.default_args.iter().map(|s| s.to_string()).collect();
128        let checks = payload.default_checks.to_vec();
129        Self {
130            ctx,
131            payload,
132            args,
133            checks,
134            cgroup: None,
135            timeout: None,
136        }
137    }
138
139    /// Append one CLI argument to the effective argv.
140    #[must_use = "builder methods consume self; bind the result"]
141    pub fn arg(mut self, arg: impl Into<String>) -> Self {
142        self.args.push(arg.into());
143        self
144    }
145
146    /// Append multiple CLI arguments to the effective argv.
147    #[must_use = "builder methods consume self; bind the result"]
148    pub fn args<I, S>(mut self, args: I) -> Self
149    where
150        I: IntoIterator<Item = S>,
151        S: Into<String>,
152    {
153        self.args.extend(args.into_iter().map(Into::into));
154        self
155    }
156
157    /// Wipe ALL args (both `payload.default_args` and any prior
158    /// `.arg()` calls). Subsequent `.arg()` calls start from empty.
159    #[must_use = "builder methods consume self; bind the result"]
160    pub fn clear_args(mut self) -> Self {
161        self.args.clear();
162        self
163    }
164
165    /// Append a [`MetricCheck`] to the effective check list.
166    #[must_use = "builder methods consume self; bind the result"]
167    pub fn check(mut self, c: MetricCheck) -> Self {
168        self.checks.push(c);
169        self
170    }
171
172    /// Wipe ALL checks (both `payload.default_checks` and any prior
173    /// `.check()` calls).
174    #[must_use = "builder methods consume self; bind the result"]
175    pub fn clear_checks(mut self) -> Self {
176        self.checks.clear();
177        self
178    }
179
180    /// Place the spawned child in the named cgroup (a plain name,
181    /// resolved relative to `ctx.cgroups.parent_path()`). When
182    /// omitted, the child inherits the spawning process's cgroup.
183    ///
184    /// Accepts `&'static str` (zero-alloc, the common case of a
185    /// const cgroup name) or any owned string type via [`Cow`]'s
186    /// `From` impls.
187    ///
188    /// The name is validated at `.run()`/`.spawn()` — leading `/`
189    /// is stripped, `..` and NUL bytes are rejected.
190    #[must_use = "builder methods consume self; bind the result"]
191    pub fn in_cgroup(mut self, name: impl Into<Cow<'static, str>>) -> Self {
192        self.cgroup = Some(name.into());
193        self
194    }
195
196    /// Bound `.run()`'s wait for the payload to exit. `None` (the
197    /// default when `.timeout` is not called) waits indefinitely —
198    /// suitable for payloads whose runtime is bounded internally
199    /// (schbench `-r 10`, fio `--runtime`, ...). `Some(duration)`
200    /// arms a deadline watchdog inside `.run()` that SIGKILLs the
201    /// payload's whole process group if it has not exited by the
202    /// deadline. Ignored by `.spawn()` — background handles manage
203    /// their own timing.
204    ///
205    /// The builder shape keeps `.run()` zero-arg so non-timeout
206    /// call sites read naturally, and leaves room for future
207    /// knobs (per-test environment, stdin, …) without another
208    /// signature break.
209    #[must_use = "builder methods consume self; bind the result"]
210    pub fn timeout(mut self, duration: Duration) -> Self {
211        self.timeout = Some(duration);
212        self
213    }
214
215    /// Blocking foreground run. Spawns the payload binary, waits
216    /// for it to exit, extracts metrics from its output per the
217    /// payload's [`OutputFormat`](crate::test_support::OutputFormat) (stdout-primary with stderr
218    /// fallback for `Json`; no extraction for
219    /// `ExitCode`), and evaluates declared [`MetricCheck`]s into an
220    /// [`AssertResult`]. See the module-level
221    /// `# Stdout-primary, stderr-fallback metric extraction`
222    /// section for the full contract.
223    ///
224    /// Runtime is bounded by the value set via
225    /// [`timeout`](Self::timeout). When the deadline expires,
226    /// `kill_payload_process_group` fires and the returned
227    /// `(AssertResult, PayloadMetrics)` reflects the captured
228    /// output plus the killed-child exit code; `status.code()`
229    /// returns `None` for a SIGKILL'd child, which
230    /// `spawn_and_wait` surfaces as `exit_code = -1` in
231    /// `SpawnOutput`. The timeout case is not an error — the
232    /// caller can still inspect metrics collected before the kill.
233    /// A post-kill drain failure is reported as `Err` (wraps the
234    /// original I/O error with "drain after timeout of N"); the
235    /// caller loses no output that was already captured because
236    /// the partial reader-thread buffers have been consumed in
237    /// the error path too.
238    ///
239    /// Metrics are also recorded to the per-test sidecar via the
240    /// SHM ring; the returned tuple is a convenience view of the
241    /// same values.
242    ///
243    /// Returns `Err` when the payload is not
244    /// [`PayloadKind::Binary`] (schedulers are framework-launched,
245    /// not test-body-launched), when the cgroup name fails
246    /// validation, when the spawn itself fails, or when post-kill
247    /// drain fails (see the timeout paragraph).
248    pub fn run(self) -> Result<(AssertResult, PayloadMetrics)> {
249        let binary = payload_binary(self.payload)?;
250        let cgroup_path = resolve_cgroup_path(self.ctx, self.cgroup.as_deref(), "PayloadRun::run")?;
251        let cgroup_arg: Option<(&str, &std::path::Path)> = cgroup_path.as_deref().map(|path| {
252            (
253                self.cgroup
254                    .as_deref()
255                    .expect("cgroup_path Some ⇒ cgroup name Some"),
256                path,
257            )
258        });
259        let output = spawn_and_wait(
260            binary,
261            &self.args,
262            cgroup_arg,
263            self.timeout,
264            self.payload.uses_parent_pgrp,
265            self.ctx.cgroups,
266        )
267        .with_context(|| format!("spawn payload '{}'", self.payload.name))?;
268        Ok(evaluate(self.payload, &self.checks, output))
269    }
270
271    /// Spawn the payload binary in the background and return a
272    /// [`PayloadHandle`] the caller can `.wait()`, `.kill()`, or
273    /// `.try_wait()` on.
274    ///
275    /// The child runs in the guest's process namespace (all ktstr
276    /// tests execute inside the VM); `PayloadHandle` is a thin
277    /// wrapper over [`std::process::Child`]. No cross-VM proxy.
278    ///
279    /// Dropping the handle without first calling one of the waiters
280    /// emits a stderr warning and SIGKILLs the child — leaked
281    /// handles would lose metrics and potentially outlive the test.
282    ///
283    /// Returns `Err` when the payload is not
284    /// [`PayloadKind::Binary`] or when the spawn itself fails.
285    pub fn spawn(self) -> Result<PayloadHandle> {
286        let binary = payload_binary(self.payload)?;
287        let cgroup_path =
288            resolve_cgroup_path(self.ctx, self.cgroup.as_deref(), "PayloadRun::spawn")?;
289        let cgroup_arg: Option<(&str, &std::path::Path)> = cgroup_path.as_deref().map(|path| {
290            (
291                self.cgroup
292                    .as_deref()
293                    .expect("cgroup_path Some ⇒ cgroup name Some"),
294                path,
295            )
296        });
297        let (child, sigchld) = spawn_child(
298            binary,
299            &self.args,
300            cgroup_arg,
301            self.payload.uses_parent_pgrp,
302            self.ctx.cgroups,
303        )
304        .with_context(|| format!("spawn payload '{}'", self.payload.name))?;
305        Ok(PayloadHandle {
306            child: Some(child),
307            payload: self.payload,
308            checks: self.checks,
309            _sigchld: sigchld,
310        })
311    }
312}
313
314/// Unwrap [`PayloadKind::Binary`] to its binary name, erroring when
315/// a scheduler-kind payload is passed.
316fn payload_binary(payload: &Payload) -> Result<&'static str> {
317    match payload.kind {
318        PayloadKind::Binary(name) => Ok(name),
319        PayloadKind::Scheduler(_) => anyhow::bail!(
320            "ctx.payload({}) called on a scheduler-kind payload; \
321             schedulers are launched by the test framework, not from \
322             the test body. Use ctx.payload(&BINARY_PAYLOAD) instead.",
323            payload.name,
324        ),
325    }
326}
327
328/// Common post-exit pipeline: extract metrics, resolve polarities,
329/// evaluate checks. Shared between foreground `.run()` and
330/// background handle `wait`/`kill` paths. The [`crate::test_support::PayloadMetrics`] is
331/// serialized to the guest-to-host SHM ring here — once per
332/// invocation — so the host can reconstruct per-call provenance in
333/// the sidecar without any Ctx-side accumulator.
334///
335/// # Per-format behavior
336///
337/// `OutputFormat::ExitCode` and `OutputFormat::Json` extract
338/// in-process: stdout-primary with a stderr fallback when stdout
339/// yields an empty metric set. The streams are never concatenated —
340/// the two drain threads in [`wait_and_capture`] run concurrently and
341/// provide no ordering guarantee, so a merged blob would corrupt any
342/// document whose bytes span both. Stderr is still passed separately
343/// to [`evaluate_checks`] so the exit-code-mismatch detail renders
344/// stderr without stdout prefix.
345fn evaluate(
346    payload: &Payload,
347    checks: &[MetricCheck],
348    output: SpawnOutput,
349) -> (AssertResult, PayloadMetrics) {
350    // `extract_metrics` is infallible for both `ExitCode` and `Json`
351    // (the two OutputFormat variants); the `Result` return type is
352    // preserved only for a uniform call signature.
353    let stdout_result = extract_metrics(
354        &output.stdout,
355        &payload.output,
356        crate::test_support::MetricStream::Stdout,
357    );
358    let mut metrics = stdout_result.unwrap_or_default();
359    if metrics.is_empty() && !output.stderr.is_empty() {
360        // Stderr fallback — runs only when stdout produced no
361        // metrics. Variant-agnostic by design:
362        //
363        // * `ExitCode`: `extract_metrics` returns `Ok(vec![])` on
364        //   both stdout and stderr for this variant (no parsing
365        //   path), so running the fallback is a no-op — no stored
366        //   state, no wasted work beyond one function call. A
367        //   per-variant gate would be complexity without behavioral
368        //   difference.
369        // * `Json`: BENEFITS from the fallback. The motivating case
370        //   is schbench-like payloads that write structured output
371        //   to stderr only (see `SchbenchJsonPayload` in
372        //   tests/common/fixtures.rs for the long-form rationale).
373        //
374        // The streams are never merged — fallback replaces, not
375        // concatenates — so an upstream that genuinely writes to
376        // both stdout and stderr gets only the stdout metrics,
377        // which matches the "well-behaved binaries keep stdout
378        // canonical" language on the `OutputFormat` doc.
379        let stderr_result = extract_metrics(
380            &output.stderr,
381            &payload.output,
382            crate::test_support::MetricStream::Stderr,
383        );
384        if let Ok(m) = stderr_result {
385            metrics = m;
386        }
387    }
388    resolve_polarities(&mut metrics, payload);
389
390    let payload_metrics = PayloadMetrics {
391        payload_index: next_payload_index(),
392        metrics,
393        exit_code: output.exit_code,
394    };
395
396    emit_payload_metrics(&payload_metrics);
397
398    let result = evaluate_checks(checks, &payload_metrics, &output.stderr);
399    (result, payload_metrics)
400}
401
402/// Emit a [`crate::test_support::PayloadMetrics`] on the guest-to-host bulk data channel
403/// (virtio-console port 1) under
404/// `MSG_TYPE_PAYLOAD_METRICS`(crate::vmm::wire::MSG_TYPE_PAYLOAD_METRICS).
405///
406/// The encoding (postcard v1) and the bulk-port fire-and-forget
407/// semantics live inside
408/// [`crate::vmm::guest_comms::send_payload_metrics`]; this thin
409/// wrapper exists only so the call site reads as the post-extraction
410/// emit step rather than reaching across modules. Backpressure is
411/// handled inside `write_msg`: a busy port-1 virtqueue blocks the
412/// writer until the host's `add_used` rate catches up.
413///
414/// Forwards the underlying `send_payload_metrics` boolean: `true`
415/// when the frame was written, `false` when the bulk port was not
416/// open, the write failed, or the call ran in host context (the
417/// `assert_guest_context` early-return). The emit call site in
418/// `evaluate` discards it at statement position; the boolean exists
419/// so the host-context no-op is observable to a test.
420fn emit_payload_metrics(pm: &PayloadMetrics) -> bool {
421    crate::vmm::guest_comms::send_payload_metrics(pm)
422}
423
424// ---------------------------------------------------------------------------
425// PayloadHandle — background spawn result
426// ---------------------------------------------------------------------------
427
428/// Handle to a background payload spawned via
429/// [`PayloadRun::spawn`]. Wraps a guest-local
430/// [`std::process::Child`]; `wait` / `kill` both consume the handle
431/// and return the collected metrics + assertion verdict.
432///
433/// Drop behavior: if the handle is dropped without `wait`/`kill`,
434/// the child and every process it forked are SIGKILLed via the
435/// process group headed by the child, then the child is reaped with
436/// `child.wait()`, and a stderr warning is emitted so the test
437/// author sees the implicit drop. The process-group kill reaches
438/// every descendant of multi-process payloads (stress-ng, schbench
439/// worker mode, fio `--numjobs`); without it the orphans keep
440/// stdout/stderr open, block `wait_and_capture`, and lose metrics.
441///
442/// When multiple handles are active, sidecar entries appear in
443/// finalization order (the order `.wait()`, `.kill()`, or
444/// `.try_wait()` returning `Ok(Some(..))` are called), not spawn
445/// order. `.try_wait()` only records on its terminal branch; an
446/// `Ok(None)` return keeps the handle live and defers the sidecar
447/// write to the next terminal call.
448// DROP-ORDER-CRITICAL: keep `_sigchld` LAST in the field list.
449//
450// Rust drops fields in declaration order, so the LAST field is the
451// LAST to drop. `SigchldScope::drop` re-installs the previously
452// captured disposition; multiple live `SigchldScope`s on the same
453// thread form a LIFO stack whose unwinding is what restores the
454// outermost original disposition. Any field added between `child`
455// and `_sigchld` would still keep `_sigchld` last, but a field
456// added AFTER `_sigchld` would reorder the drop sequence and break
457// the LIFO invariant — drop the new field first, signal-restore
458// path runs second, the disposition handler captured BEFORE the
459// new field was constructed gets restored even though the new
460// field outlived nothing. Also: when the caller holds two
461// `PayloadHandle`s and drops them in non-creation order, the LIFO
462// invariant is preserved by the field-order rule WITHIN each
463// handle but not ACROSS handles — non-LIFO drop across handles
464// will leak `SIG_DFL` into the rest of the process. Test authors
465// must drop handles in reverse creation order; the LIFO test in
466// the unit-test module pins the within-handle field-order rule
467// to catch a future refactor that re-orders the struct.
468#[must_use = "dropping a PayloadHandle SIGKILLs the child's process group; call .wait() or .kill() explicitly"]
469pub struct PayloadHandle {
470    /// Live child process. Wrapped in `Option` so consumers can
471    /// take ownership in `wait`/`kill` without making the drop-guard
472    /// reach into a `None`.
473    child: Option<std::process::Child>,
474    payload: &'static Payload,
475    checks: Vec<MetricCheck>,
476    /// `SIGCHLD` guard installed at spawn time. Kept alive until
477    /// the handle is consumed (via `wait`/`kill`/Drop) so the
478    /// child's eventual `waitpid` sees `SIG_DFL` instead of the
479    /// guest init's `SIG_IGN`. See [`SigchldScope`] for the full
480    /// rationale.
481    ///
482    /// DROP-ORDER-CRITICAL: keep this field LAST. See struct-level
483    /// note above.
484    _sigchld: SigchldScope,
485}
486
487impl std::fmt::Debug for PayloadHandle {
488    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
489        // Payload's manual Debug renders identity fields; the inner
490        // Child is omitted (not Debug-rendering-friendly and carries
491        // OS handles) — a one-line summary is enough for panics /
492        // test output.
493        f.debug_struct("PayloadHandle")
494            .field("payload", &self.payload.name)
495            .field("child_alive", &self.child.is_some())
496            .field("checks_len", &self.checks.len())
497            .finish()
498    }
499}
500
501impl PayloadHandle {
502    /// Name of the [`Payload`] this handle was spawned from — i.e.
503    /// the identity key used by step-level ops to address a running
504    /// payload. Step-local ops ([`Op::WaitPayload`](crate::scenario::ops::Op::WaitPayload),
505    /// [`Op::KillPayload`](crate::scenario::ops::Op::KillPayload))
506    /// match handles by this name.
507    pub fn payload_name(&self) -> &'static str {
508        self.payload.name
509    }
510
511    /// Live child's OS-level pid, or `None` once `wait`/`kill`/
512    /// `try_wait` has consumed the child.
513    ///
514    /// Integration tests that spawn a workload and then need to
515    /// target it with a second tool (for example the jemalloc-TLS
516    /// probe in `tests/jemalloc_probe_tests.rs`, which passes the
517    /// workload's pid to `ktstr-jemalloc-probe --pid`) read this
518    /// value between `spawn` and `wait`/`kill`/`try_wait`. The
519    /// internal fork-descendant reap test also uses it to probe
520    /// the process group via `killpg(_, 0)` after `kill()` without
521    /// reaching into the private `child` field.
522    pub fn pid(&self) -> Option<u32> {
523        self.child.as_ref().map(|c| c.id())
524    }
525
526    /// Block until the child exits naturally, then extract metrics
527    /// and evaluate checks, matching the foreground `.run()` return
528    /// shape.
529    ///
530    /// Metrics are also recorded to the per-test sidecar via the
531    /// SHM ring; the returned tuple is a convenience view of the
532    /// same values.
533    pub fn wait(mut self) -> Result<(AssertResult, PayloadMetrics)> {
534        let mut child = self
535            .child
536            .take()
537            .ok_or_else(|| already_consumed(self.payload))?;
538        // Block until the leader exits naturally first, BEFORE
539        // spawning reader threads inside `wait_and_capture`. Then
540        // killpg the group to reap any descendants (stress-ng workers,
541        // schbench worker mode, fio --numjobs threads) that survived
542        // the leader and still hold the inherited stdout/stderr pipes
543        // open. Without this killpg-before-drain step the reader
544        // threads would block forever waiting for descendants to
545        // release the pipes — the same blocking-pipe failure mode
546        // that try_wait's kill_payload_process_group step guards
547        // against. `Child::wait`
548        // caches the exit status so the second call inside
549        // `wait_and_capture` returns immediately without a syscall.
550        if let Err(e) = child.wait() {
551            kill_payload_process_group(&child, self.payload.name, self.payload.uses_parent_pgrp);
552            let _ = child.wait();
553            return Err(e).with_context(|| format!("wait payload '{}'", self.payload.name));
554        }
555        kill_payload_process_group(&child, self.payload.name, self.payload.uses_parent_pgrp);
556        match wait_and_capture(&mut child) {
557            Ok(output) => Ok(evaluate(self.payload, &self.checks, output)),
558            Err(e) => {
559                // killpg already ran above; one more `wait` clears
560                // the zombie so the pid slot is freed regardless of
561                // the capture error.
562                let _ = child.wait();
563                Err(e).with_context(|| format!("wait payload '{}'", self.payload.name))
564            }
565        }
566    }
567
568    /// SIGKILL the child **and every process it forked**, reap it,
569    /// and return whatever stdout+stderr was captured along with the
570    /// process exit code. Suitable for time-boxed background loads.
571    ///
572    /// The signal is delivered via `killpg(child_pid, SIGKILL)`
573    /// rather than `child.kill()` because `build_command` places the
574    /// payload at the head of its own process group. Multi-process
575    /// payloads (stress-ng, schbench worker mode, fio --numjobs) fork
576    /// descendants that keep stdout/stderr open; killing only the
577    /// head would orphan those writers and block
578    /// `wait_and_capture` forever, losing every metric.
579    ///
580    /// Metrics are also recorded to the per-test sidecar via the
581    /// SHM ring; the returned tuple is a convenience view of the
582    /// same values.
583    pub fn kill(mut self) -> Result<(AssertResult, PayloadMetrics)> {
584        let mut child = self
585            .child
586            .take()
587            .ok_or_else(|| already_consumed(self.payload))?;
588        kill_payload_process_group(&child, self.payload.name, self.payload.uses_parent_pgrp);
589        match wait_and_capture(&mut child) {
590            Ok(output) => Ok(evaluate(self.payload, &self.checks, output)),
591            Err(e) => {
592                // killpg + single-pid SIGKILL already ran at the
593                // start; the reap or pipe-drain failed afterwards.
594                // One more `wait` clears the zombie so the pid slot
595                // is freed regardless of the capture error.
596                let _ = child.wait();
597                Err(e).with_context(|| format!("reap killed payload '{}'", self.payload.name))
598            }
599        }
600    }
601
602    /// Non-blocking check for exit without consuming the handle.
603    /// Returns `Ok(Some((result, metrics)))` once the child has
604    /// exited and output is drained; `Ok(None)` while still
605    /// running. The handle remains live on `Ok(None)`.
606    ///
607    /// On the terminal `Ok(Some(..))` return, metrics are also
608    /// recorded to the per-test sidecar via the SHM ring; the
609    /// returned tuple is a convenience view of the same values.
610    pub fn try_wait(&mut self) -> Result<Option<(AssertResult, PayloadMetrics)>> {
611        let child = self
612            .child
613            .as_mut()
614            .ok_or_else(|| already_consumed(self.payload))?;
615        match child.try_wait()? {
616            Some(_status) => {
617                // `child` was Some above; the earlier branch didn't
618                // `take()` it, so this unwrap is guaranteed to hold.
619                let mut child = self
620                    .child
621                    .take()
622                    .expect("child still present on terminal branch");
623                // The leader has exited (try_wait returned Some), but
624                // descendants forked off the leader (stress-ng workers,
625                // schbench worker mode, fio --numjobs threads) may
626                // still be alive and holding the inherited
627                // stdout/stderr pipes open. Without first SIGKILLing
628                // the process group, `wait_and_capture` would block
629                // forever on the read syscall waiting for those
630                // descendants to release the pipes. This mirrors the
631                // kill() path's kill_payload_process_group call which
632                // always SIGKILLs the group before draining — the
633                // only difference here is
634                // the leader has already exited, so killpg is reaping
635                // descendants only.
636                kill_payload_process_group(
637                    &child,
638                    self.payload.name,
639                    self.payload.uses_parent_pgrp,
640                );
641                match wait_and_capture(&mut child) {
642                    Ok(output) => Ok(Some(evaluate(self.payload, &self.checks, output))),
643                    Err(e) => {
644                        // killpg + single-pid SIGKILL already ran at
645                        // the top of this branch; the reap or
646                        // pipe-drain failed afterwards. One more
647                        // `wait` clears the zombie so the pid slot is
648                        // freed regardless of the capture error.
649                        let _ = child.wait();
650                        Err(e).with_context(|| format!("reap payload '{}'", self.payload.name))
651                    }
652                }
653            }
654            None => Ok(None),
655        }
656    }
657}
658
659/// Error value produced when `wait`/`kill`/`try_wait` is called on a
660/// handle whose child has already been taken by a prior call. The
661/// payload name anchors the error to a specific handle so the
662/// test log points directly at the misuse site.
663fn already_consumed(payload: &'static Payload) -> anyhow::Error {
664    anyhow!(
665        "PayloadHandle for '{}' already consumed by a prior \
666         wait/kill/try_wait call; each handle can only produce \
667         one (AssertResult, PayloadMetrics) pair",
668        payload.name,
669    )
670}
671
672/// Drop-safety net for handles that fall out of scope without
673/// going through [`PayloadHandle::wait`], [`PayloadHandle::kill`],
674/// or [`PayloadHandle::try_wait`] (the three paths that
675/// `.take()` the child normally). Drop routes the process group
676/// through `kill_payload_process_group` — the SAME kill path the
677/// explicit `kill()` method uses — so there is no redundant
678/// `child.kill()` call: the killpg + single-pid SIGKILL inside
679/// `kill_payload_process_group` is belt-and-suspenders-by-design
680/// (see its doc for the pre-exec ESRCH race rationale), not
681/// two independent kills stacked. `child.wait()` reaps the
682/// zombie so the pid slot is freed even on the "dropped without
683/// consume" path, and the one-shot eprintln tells the operator
684/// metrics were lost.
685impl Drop for PayloadHandle {
686    fn drop(&mut self) {
687        if let Some(mut child) = self.child.take() {
688            kill_payload_process_group(&child, self.payload.name, self.payload.uses_parent_pgrp);
689            let _ = child.wait();
690            eprintln!(
691                "ktstr: PayloadHandle for '{}' dropped without wait/kill — \
692                 process group SIGKILLed, metrics not recorded.",
693                self.payload.name,
694            );
695        }
696    }
697}
698
699/// Send `SIGKILL` to the process group headed by `child` AND to the
700/// leader pid directly.
701///
702/// `build_command` requests `CommandExt::process_group(0)` by default
703/// so the child's pid becomes its own process-group leader, coordinated
704/// with exec setup by the standard library. `killpg(pgid, SIGKILL)`
705/// on the child's pid therefore reaches every fork descendant in
706/// one shot — a single `child.kill()` would otherwise miss
707/// grandchildren of multi-process payloads (stress-ng, schbench
708/// worker mode, fio --numjobs) and those orphans would keep the
709/// stdout/stderr pipes open, hanging `wait_and_capture` forever.
710///
711/// When `uses_parent_pgrp` is `true`, the child shares its parent's
712/// pgrp ([`Payload::uses_parent_pgrp`] opted out of the fresh
713/// process group for tty-dependent binaries). The `killpg` call is
714/// skipped entirely in that case — issuing it would either hit
715/// `ESRCH` (child is not a pgrp leader) in the common case or, worse,
716/// target an unrelated group if the pgrp id happened to match a stale
717/// value. Only the direct `kill(pid)` on the leader runs; opt-out
718/// payloads accept responsibility for cleaning up their own
719/// descendants.
720///
721/// The follow-up `kill(pid, SIGKILL)` on the leader pid is
722/// belt-and-suspenders coverage for the edge case where `killpg`
723/// alone is insufficient: the kernel-side pgid transition during
724/// exec may not have completed yet when `killpg` fires, so
725/// `killpg` returns `ESRCH` (no such group) and the leader
726/// survives. A direct `kill(pid, SIGKILL)` always reaches the
727/// leader, and the SIGKILL survives `execve(2)` to take effect
728/// once exec completes (signal disposition is preserved across
729/// exec; the pending signal is delivered once the new image
730/// starts). SIGKILL is idempotent against zombies and
731/// already-dead processes, so the extra signal is safe after a
732/// successful `killpg` — a killpg that reached the leader has
733/// already queued it for SIGKILL, and the follow-up `kill(pid)`
734/// is a no-op on the terminated process.
735///
736/// `child.id()` returns `u32` for API ergonomics; on Linux the
737/// kernel's `pid_max ≤ 2²²` guarantees the value fits in
738/// [`libc::pid_t`]'s positive `i32` range, so `try_from` succeeds on
739/// every live child. `debug_assert!(pgid > 0)` catches the
740/// theoretically-impossible non-positive case before
741/// [`nix::sys::signal::killpg`] would otherwise interpret it as a
742/// broadcast target. `ESRCH` is logged as-a-no-op for both calls
743/// — it means either "group/process already reaped" or "group not
744/// yet set up"; the follow-up direct `kill` plus the leader's
745/// eventual `waitpid` consumer handle both.
746///
747/// # Process-group escape (not handled here)
748///
749/// `killpg` reaches every process whose `getpgrp()` equals the
750/// leader's pgid. A descendant that calls `setpgid(0, 0)` or
751/// `setsid(2)` between fork and exit leaves the leader's process
752/// group and becomes invisible to this helper — the escaping
753/// descendant keeps running after SIGKILL and may continue holding
754/// pipe fds that stall `wait_and_capture`. The bundled payloads
755/// (stress-ng, schbench, fio) have not been audited for these
756/// syscalls. `build_command` does not place an exec'd
757/// child into any other group; this limitation applies only to
758/// third-party payloads that deliberately re-parent themselves. The
759/// mitigation path is the caller's: wrap the misbehaving payload in
760/// a shell that traps SIGTERM → SIGKILL of its own descendants, or
761/// register the leader as a subreaper
762/// (`PR_SET_CHILD_SUBREAPER`) and reap orphans explicitly.
763///
764/// # Caller contract
765///
766/// Every caller MUST hold a live [`SigchldScope`] for the duration of
767/// the `wait` / `waitpid` that reaps the leader after this call
768/// returns. Without `SIG_DFL` for `SIGCHLD`, the guest init's
769/// `SIG_IGN` default causes `wait` to block until the child is
770/// re-reaped by init or to return `ECHILD` on an already-ignored
771/// SIGCHLD. Audited caller set — every invocation of this function:
772///
773/// - `PayloadHandle::wait` (one site: error arm after a
774///   `wait_and_capture` failure) — holds `self._sigchld`.
775/// - `PayloadHandle::kill` (one site: top of the method, before
776///   drain) — holds `self._sigchld`.
777/// - `PayloadHandle::try_wait` (one site: error arm after a
778///   terminal `try_wait` when drain fails) — holds `self._sigchld`.
779/// - `impl Drop for PayloadHandle` (one site: handle dropped without
780///   an explicit `wait`/`kill`/`try_wait` consume) — holds
781///   `self._sigchld` for the full Drop body.
782/// - `spawn_and_wait` (one site: error arm when `wait_and_capture`
783///   fails on a timeout-less foreground spawn) — opens a local
784///   `let _sigchld = SigchldScope::new()` at the top of the
785///   function.
786/// - `wait_with_deadline` (two sites: deadline-miss kill on expiry,
787///   and error arm for drain failure on natural child exit) — runs
788///   inside `spawn_and_wait`'s `_sigchld` scope, which is held
789///   across the callee as a local binding.
790///
791/// Every `PayloadHandle` method is safe because `_sigchld` is
792/// declared after `child` in the struct body; Rust drops fields in
793/// declaration order so `_sigchld` lives longer than the child
794/// `Option`, keeping the scope live for the full method body.
795///
796/// A future caller that skips either pattern will see
797/// `waitpid` hang on some guest runtimes — add a `SigchldScope` at
798/// the call site, or extend an enclosing type with a
799/// `_sigchld: SigchldScope` field, before landing.
800fn kill_payload_process_group(
801    child: &std::process::Child,
802    payload_name: &str,
803    uses_parent_pgrp: bool,
804) {
805    let raw_pid = child.id();
806    let pgid = match libc::pid_t::try_from(raw_pid) {
807        Ok(p) if p > 0 => p,
808        Ok(p) => {
809            tracing::error!(
810                payload = payload_name,
811                pid = p,
812                "child pid is non-positive — cannot kill process group; \
813                 skipping kill (kernel's pid_max invariant violated, \
814                 no safe target)"
815            );
816            return;
817        }
818        Err(_) => {
819            tracing::error!(
820                payload = payload_name,
821                pid = raw_pid,
822                "child pid exceeds pid_t range — cannot kill process group; \
823                 skipping kill (Linux pid_max is 2^22 so this is only \
824                 reachable on a non-Linux target or a kernel with an \
825                 extended pid space)"
826            );
827            return;
828        }
829    };
830    let pid = nix::unistd::Pid::from_raw(pgid);
831    // `uses_parent_pgrp=true` means `build_command` did NOT request
832    // `process_group(0)`, so the child shares its parent's process
833    // group. A `killpg(pgid=child_pid, …)` call would target a group
834    // the child does not lead — `ESRCH` in the common case, or (worse)
835    // reach the ktstr process itself if a stale pid matches. Skip the
836    // group kill entirely and rely on the direct `kill(pid)` below to
837    // reap the leader. Multi-process tty-dependent payloads that
838    // opt out of the fresh pgrp accept responsibility for their own
839    // descendant cleanup (see `Payload::uses_parent_pgrp` doc).
840    if !uses_parent_pgrp {
841        match nix::sys::signal::killpg(pid, nix::sys::signal::Signal::SIGKILL) {
842            Ok(()) => {}
843            Err(nix::errno::Errno::ESRCH) => {
844                tracing::debug!(
845                    payload = payload_name,
846                    pgid,
847                    "ESRCH — payload process group already reaped",
848                );
849            }
850            Err(e) => {
851                tracing::warn!(payload = payload_name, pgid, %e, "killpg failed for payload process group");
852            }
853        }
854    }
855    match nix::sys::signal::kill(pid, nix::sys::signal::Signal::SIGKILL) {
856        Ok(()) => {}
857        Err(nix::errno::Errno::ESRCH) => {
858            tracing::debug!(
859                payload = payload_name,
860                pid = pgid,
861                "ESRCH — payload leader already reaped",
862            );
863        }
864        Err(e) => {
865            tracing::warn!(payload = payload_name, pid = pgid, %e, "direct kill failed for payload leader");
866        }
867    }
868}
869
870/// Resolve each extracted metric's polarity + unit against the
871/// payload's declared `metrics` hints.
872///
873/// Unhinted metrics keep [`crate::test_support::Polarity::Unknown`] and empty unit.
874///
875/// Complexity: O(N + M) — build a `HashMap<&str, &MetricHint>` from
876/// the hint slice once, then look up each metric by name in O(1).
877/// The prior linear-scan implementation was O(N × M) where N is
878/// extracted metrics and M is declared hints; fio JSON with
879/// thousands of leaves + a dozen hints was the hottest path this
880/// module sees per payload run.
881fn resolve_polarities(metrics: &mut [Metric], payload: &Payload) {
882    if payload.metrics.is_empty() || metrics.is_empty() {
883        return;
884    }
885    let hints: std::collections::HashMap<&str, &crate::test_support::MetricHint> =
886        payload.metrics.iter().map(|h| (h.name, h)).collect();
887    for metric in metrics {
888        if let Some(hint) = hints.get(metric.name.as_str()) {
889            metric.polarity = hint.polarity;
890            metric.unit = hint.unit.to_string();
891        }
892    }
893}
894
895/// Evaluate [`MetricCheck`]s against a [`crate::test_support::PayloadMetrics`] and fold the
896/// verdict into an [`AssertResult`].
897///
898/// Evaluation order:
899/// 1. [`MetricCheck::ExitCodeEq`] pre-pass — evaluated FIRST so a
900///    misconfigured binary fails with an actionable exit-code error
901///    rather than "metric X not found".
902/// 2. Metric-path checks ([`MetricCheck::Min`], [`MetricCheck::Max`],
903///    [`MetricCheck::Range`], [`MetricCheck::Exists`]).
904///
905/// `stderr` is folded into the exit-code-mismatch detail when
906/// present — when a binary fails with "expected 0 got 1", the
907/// captured stderr almost always explains why, and forcing the test
908/// author to go hunt it down defeats actionable diagnostics.
909///
910/// Missing metrics fail loudly — a `Min` / `Max` / `Range` / `Exists`
911/// check against an absent metric reports a "not found" detail
912/// instead of silently passing.
913fn evaluate_checks(checks: &[MetricCheck], pm: &PayloadMetrics, stderr: &str) -> AssertResult {
914    let mut result = AssertResult::pass();
915    // Pre-pass: exit-code checks first. Delegates to
916    // `exit_code_mismatch_detail` for the detail's kind + message.
917    // Short-circuit on mismatch — a bad exit probably means the
918    // metric extraction found nothing useful.
919    if let Some(detail) = exit_code_mismatch_detail(checks, pm.exit_code, stderr) {
920        result.merge(AssertResult::fail(detail));
921        return result;
922    }
923    // Metric-path pass.
924    //
925    // Each comparator below routes a NaN observed value through
926    // `nan_metric` BEFORE the bound comparison. IEEE 754 makes
927    // every comparison against NaN evaluate to false (`NaN < x`,
928    // `NaN > x`, and `NaN == x` are all false), which would let
929    // a NaN-valued metric silently pass `Min` / `Max` / `Range` —
930    // exactly the case operators most need to flag, since a NaN
931    // value indicates the payload's metric extraction itself is
932    // broken (a divide-by-zero, an unparsed token, or a typed-
933    // measurement error). Surface NaN as a hard failure with a
934    // dedicated message so the bound check never silently green-
935    // lights an unmeasurable value.
936    for check in checks {
937        let detail = match check {
938            MetricCheck::Min { metric, value } => pm.get(metric).map_or_else(
939                || Some(missing_metric(metric)),
940                |actual| {
941                    if actual.is_nan() {
942                        Some(nan_metric(metric))
943                    } else if actual < *value {
944                        Some(AssertDetail::new(
945                            DetailKind::Other,
946                            format!("metric '{metric}' = {actual} below minimum {value}"),
947                        ))
948                    } else {
949                        None
950                    }
951                },
952            ),
953            MetricCheck::Max { metric, value } => pm.get(metric).map_or_else(
954                || Some(missing_metric(metric)),
955                |actual| {
956                    if actual.is_nan() {
957                        Some(nan_metric(metric))
958                    } else if actual > *value {
959                        Some(AssertDetail::new(
960                            DetailKind::Other,
961                            format!("metric '{metric}' = {actual} exceeds maximum {value}"),
962                        ))
963                    } else {
964                        None
965                    }
966                },
967            ),
968            MetricCheck::Range { metric, lo, hi } => pm.get(metric).map_or_else(
969                || Some(missing_metric(metric)),
970                |actual| {
971                    if actual.is_nan() {
972                        Some(nan_metric(metric))
973                    } else if actual < *lo || actual > *hi {
974                        Some(AssertDetail::new(
975                            DetailKind::Other,
976                            format!("metric '{metric}' = {actual} outside [{lo}, {hi}]"),
977                        ))
978                    } else {
979                        None
980                    }
981                },
982            ),
983            MetricCheck::Exists(metric) => pm.get(metric).is_none().then(|| missing_metric(metric)),
984            MetricCheck::ExitCodeEq(_) => None, // already evaluated in pre-pass
985        };
986        if let Some(d) = detail {
987            result.merge(AssertResult::fail(d));
988        }
989    }
990    result
991}
992
993/// Build the NaN-value [`AssertDetail`] surfaced by every
994/// magnitude comparator ([`MetricCheck::Min`], [`MetricCheck::Max`],
995/// [`MetricCheck::Range`]) when a metric extracts as NaN. Pulled
996/// out so the three call sites share one message format — a
997/// renamer-resistant single source of truth that pairs naturally
998/// with [`missing_metric`] for the absent-metric counterpart.
999fn nan_metric(metric: &str) -> AssertDetail {
1000    AssertDetail::new(DetailKind::Other, format!("metric '{metric}' value is NaN"))
1001}
1002
1003fn missing_metric(metric: &str) -> AssertDetail {
1004    AssertDetail::new(
1005        DetailKind::Other,
1006        format!("metric '{metric}' not found in payload output"),
1007    )
1008}
1009
1010/// Scan `checks` for the first `MetricCheck::ExitCodeEq` whose expected
1011/// value differs from `actual_exit_code` and return a matching
1012/// diagnostic [`AssertDetail`]. Returns `None` when no
1013/// `ExitCodeEq` check is declared, or when every declared one
1014/// matches the observed exit code.
1015///
1016/// Factored out of [`evaluate_checks`]'s pre-pass so the exit-code
1017/// mismatch detail has one source of truth for kind, message format,
1018/// and the "which MetricCheck wins" order.
1019fn exit_code_mismatch_detail(
1020    checks: &[MetricCheck],
1021    actual_exit_code: i32,
1022    stderr: &str,
1023) -> Option<AssertDetail> {
1024    checks.iter().find_map(|c| match c {
1025        MetricCheck::ExitCodeEq(expected) if actual_exit_code != *expected => {
1026            Some(AssertDetail::new(
1027                DetailKind::Other,
1028                format_exit_mismatch(actual_exit_code, *expected, stderr),
1029            ))
1030        }
1031        _ => None,
1032    })
1033}
1034
1035/// Render an exit-code mismatch with a trailing stderr tail when
1036/// non-empty. Long stderr is tail-truncated (last 1 KiB) — the end
1037/// of a failing process usually carries the actionable error.
1038const STDERR_TAIL_BYTES: usize = 1024;
1039
1040fn format_exit_mismatch(actual: i32, expected: i32, stderr: &str) -> String {
1041    let trimmed = stderr.trim_end();
1042    if trimmed.is_empty() {
1043        return format!("payload exited with code {actual}, expected {expected}");
1044    }
1045    let tail = stderr_tail(trimmed, STDERR_TAIL_BYTES);
1046    format!("payload exited with code {actual}, expected {expected}; stderr:\n{tail}")
1047}
1048
1049/// Return the final `max_bytes` of `s`, snapped forward to a char
1050/// boundary so slicing never panics on multi-byte input. Emits a
1051/// leading `...` when truncation actually happens.
1052fn stderr_tail(s: &str, max_bytes: usize) -> String {
1053    if s.len() <= max_bytes {
1054        return s.to_string();
1055    }
1056    let mut start = s.len() - max_bytes;
1057    while start < s.len() && !s.is_char_boundary(start) {
1058        start += 1;
1059    }
1060    format!("...{}", &s[start..])
1061}
1062
1063/// Captured output from a payload process invocation. `stderr`
1064/// is kept so the evaluator can surface it on non-zero exit — the
1065/// extracted metrics alone don't explain why a binary failed.
1066struct SpawnOutput {
1067    stdout: String,
1068    stderr: String,
1069    exit_code: i32,
1070}
1071
1072/// Resolve the user-supplied cgroup name to an absolute path
1073/// under `ctx.cgroups.parent_path()`, validating BEFORE fork so a
1074/// bad name produces a clear error rather than a `pre_exec` failure
1075/// that surfaces as an `io::Error` after the child is already spawning.
1076///
1077/// `op` is a caller-supplied label (typically `"PayloadRun::run"`
1078/// or `"PayloadRun::spawn"`) that prefixes every validation-error
1079/// message so an operator reading the failure can identify which
1080/// Op-method bubbled the error without re-running the test.
1081///
1082/// Rules:
1083/// - `None` → child inherits caller's cgroup (returns `Ok(None)`).
1084/// - A leading `/` is tolerated and stripped so `"/workload"` and
1085///   `"workload"` behave identically.
1086/// - NUL bytes are rejected — a resolved path with an interior
1087///   NUL would truncate inside any `libc` layer that handles it.
1088///   The downstream cgroupfs write in
1089///   [`crate::cgroup::CgroupOps::place_task_during_handshake`]
1090///   would also reject the bad name, but catching it up-front
1091///   gives a clearer diagnostic than the underlying write error.
1092/// - Any `..` component is rejected to prevent the name from
1093///   escaping the parent cgroup.
1094/// - Empty names (or names that strip to empty) are rejected so a
1095///   typo doesn't silently target the parent cgroup itself.
1096fn resolve_cgroup_path(
1097    ctx: &Ctx<'_>,
1098    name: Option<&str>,
1099    op: &'static str,
1100) -> Result<Option<PathBuf>> {
1101    let Some(name) = name else {
1102        return Ok(None);
1103    };
1104    if name.as_bytes().contains(&0) {
1105        return Err(anyhow!("{op}: cgroup name '{name}' contains a NUL byte"));
1106    }
1107    let trimmed = name.trim_start_matches('/');
1108    if trimmed.is_empty() {
1109        return Err(anyhow!(
1110            "{op}: cgroup name '{name}' is empty or resolves to the parent cgroup"
1111        ));
1112    }
1113    let relative = std::path::Path::new(trimmed);
1114    if relative
1115        .components()
1116        .any(|c| matches!(c, std::path::Component::ParentDir))
1117    {
1118        return Err(anyhow!(
1119            "{op}: cgroup name '{name}' contains '..'; paths must stay within the \
1120             test's cgroup parent"
1121        ));
1122    }
1123    Ok(Some(ctx.cgroups.parent_path().join(relative)))
1124}
1125
1126/// Build a [`std::process::Command`] with args, piped stdout/stderr, a
1127/// `process_group(0)` request when the payload is not
1128/// `uses_parent_pgrp`, and (optionally) a cgroup-placement
1129/// pre_exec hook that BLOCKS the child on a read from a
1130/// caller-owned release pipe until the parent has placed the
1131/// child into the target cgroup via
1132/// [`crate::cgroup::CgroupOps::place_task_during_handshake`].
1133///
1134/// When `cgroup` is `Some((name, path))`, the returned tuple's
1135/// second element is `Some(CgroupSyncHandles)` — a parent-side
1136/// bundle of (a) the write end of the release pipe, (b) the read
1137/// end of the child-side pid-notify pipe, (c) the user-facing
1138/// `cgroup_name` the placement trait method will receive, and
1139/// (d) the absolute `cgroup.procs` path retained for diagnostic
1140/// surfaces. The caller passes it to
1141/// [`spawn_with_cgroup_sync`], which drives the placement
1142/// protocol by reading the child pid, calling
1143/// `cgroup_ops.place_task_during_handshake(cgroup_name, child_pid)`,
1144/// then releasing the child via a single-byte write on the
1145/// release pipe.
1146///
1147/// When `cgroup` is `None`, the returned handle is `None`
1148/// and callers may invoke `Command::spawn()` on the returned
1149/// `Command` directly — no placement protocol is required and
1150/// the child's cgroup is inherited from the parent (the ktstr
1151/// process).
1152///
1153/// Returns `Err` if the pipe(2) pair allocation fails.
1154fn build_command(
1155    binary: &str,
1156    args: &[String],
1157    cgroup: Option<(&str, &std::path::Path)>,
1158    uses_parent_pgrp: bool,
1159) -> Result<(std::process::Command, Option<CgroupSyncHandles>)> {
1160    use std::os::unix::process::CommandExt;
1161    use std::process::{Command, Stdio};
1162
1163    let mut cmd = Command::new(binary);
1164    cmd.args(args).stdout(Stdio::piped()).stderr(Stdio::piped());
1165    if !uses_parent_pgrp {
1166        // `process_group(0)` requests a fresh process group with
1167        // the child as leader (pgid == child's pid). `killpg` on
1168        // the child's pid then reaches every fork descendant in
1169        // one signal — a single `child.kill()` would otherwise
1170        // miss grandchildren of multi-process payloads (stress-ng,
1171        // schbench worker mode, fio with multiple jobs), and
1172        // those orphans keep the stdout/stderr pipes open,
1173        // hanging `wait_and_capture` and discarding the metrics.
1174        //
1175        // Previously a hand-rolled `pre_exec(setpgid(0, 0))` hook
1176        // did the same job, but a `killpg` issued between
1177        // `fork(2)` and the child's `setpgid` completion could
1178        // return `ESRCH` (no such group) while the child and its
1179        // descendants survived. `CommandExt::process_group`
1180        // NARROWS that window: on `posix_spawn`-capable
1181        // platforms (and futures where `process_group` dispatches
1182        // to it) the pgid transition is kernel-sequenced with
1183        // exec and the race is eliminated. When the standard
1184        // library has to fall through to the fork+exec path —
1185        // which it does whenever a cgroup placement `pre_exec`
1186        // hook is also registered below, as `process_group(0)`
1187        // and any `pre_exec` together force the legacy path —
1188        // the remaining window is covered by the direct
1189        // `kill(pid, SIGKILL)` follow-up in
1190        // `kill_payload_process_group`.
1191        //
1192        // The `uses_parent_pgrp == true` branch SKIPS this call
1193        // so the child inherits the parent ktstr process's pgid.
1194        // Opt-in for tty-dependent payloads (shells, `less`,
1195        // anything that reads controlling-terminal foreground-
1196        // pgrp for job-control signalling) — a fresh pgrp reads
1197        // as "no job control" and breaks their signal
1198        // behaviour. The cost is that `killpg(child_pid, ...)`
1199        // no longer reaches descendants (the child isn't a
1200        // pgrp leader), so multi-process tty-dependent payloads
1201        // must react to SIGHUP / pipe close on their own or
1202        // risk orphaning — see the doc on `Payload::uses_parent_pgrp`.
1203        cmd.process_group(0);
1204    }
1205
1206    if let Some((cgroup_name, cgroup_path)) = cgroup {
1207        // Two-pipe cgroup-placement handshake. `notify_*` carries
1208        // the child's pid from its pre_exec hook up to the parent
1209        // so the parent can dispatch the placement call via
1210        // [`crate::cgroup::CgroupOps::place_task_during_handshake`]
1211        // (`Command::spawn()` blocks on the stdlib CLOEXEC status
1212        // pipe until the child execve's, so the pid from
1213        // `Child::id()` is NOT available to the parent in time).
1214        // `release_*` is the reverse channel — the parent writes a
1215        // single byte once the `cgroup.procs` update has been
1216        // committed, and the child's pre_exec blocks on that byte
1217        // so its execve cannot race the placement.
1218        //
1219        // Both pipes are created with O_CLOEXEC so the parent's
1220        // copies never leak to the child (only the fds we
1221        // explicitly hand into the pre_exec closure via raw fd
1222        // numbers are touched by the child, and those are closed
1223        // on execve once pre_exec returns). This matches the
1224        // pre_exec AS-safety contract — only `read(2)` /
1225        // `write(2)` / `close(2)` / `getpid(2)` run between fork
1226        // and execve, all of which are explicitly AS-safe per
1227        // POSIX.1-2017 §2.4.3.
1228        let notify = PipePair::new().context("allocate cgroup sync pid-notify pipe")?;
1229        let release = PipePair::new().context("allocate cgroup sync release pipe")?;
1230        let notify_read_fd = notify.r_fd();
1231        let notify_write_fd = notify.w_fd();
1232        let release_read_fd = release.r_fd();
1233        let release_write_fd = release.w_fd();
1234        // SAFETY: the pre_exec closure runs in the child between
1235        // fork and execve. The body uses only getpid / write /
1236        // read / close, all AS-safe. All four fds are raw numbers
1237        // inherited by the child via the fork; the pre_exec hook
1238        // ALSO closes the child's own inherited copies of the
1239        // ends the parent will hold (`notify_read_fd`,
1240        // `release_write_fd`) BEFORE blocking on read, so the
1241        // parent's drop of the release write end actually reaches
1242        // the child as EOF instead of being masked by the child's
1243        // own inherited writer copy (which would otherwise leave
1244        // `read(release_read_fd)` blocked indefinitely — the
1245        // cross-fork pipe-sync deadlock). On the parent side we
1246        // hold owned copies in `notify` / `release` which we
1247        // close after consuming them in `drive_cgroup_handshake`.
1248        unsafe {
1249            cmd.pre_exec(move || {
1250                cgroup_sync_pre_exec(
1251                    notify_read_fd,
1252                    notify_write_fd,
1253                    release_read_fd,
1254                    release_write_fd,
1255                )
1256            });
1257        }
1258        let handles = CgroupSyncHandles {
1259            notify,
1260            release,
1261            cgroup_name: cgroup_name.to_string(),
1262            cgroup_procs_path: cgroup_path.join("cgroup.procs"),
1263        };
1264        return Ok((cmd, Some(handles)));
1265    }
1266    Ok((cmd, None))
1267}
1268
1269/// Owned pipe(2) pair. Tracks both fds as raw numbers so the
1270/// struct stays `Copy`-free and explicit about lifetime (closed
1271/// via `Drop` when no longer needed). The parent keeps one half
1272/// of each direction; the other halves are inherited by the
1273/// child through fork and consumed by `cgroup_sync_pre_exec`.
1274///
1275/// `O_CLOEXEC` is set on both ends at creation via `pipe2(2)` so
1276/// the parent's references do not leak into any subsequent
1277/// `Command::spawn()` that might run from a reader thread while
1278/// the handshake is in flight. The child's copies are closed by
1279/// the kernel on execve.
1280struct PipePair {
1281    read_fd: std::os::fd::OwnedFd,
1282    write_fd: std::os::fd::OwnedFd,
1283}
1284
1285impl PipePair {
1286    fn new() -> std::io::Result<Self> {
1287        use std::os::fd::FromRawFd;
1288        let mut fds = [0i32; 2];
1289        // SAFETY: `pipe2` writes two fds into the provided slot on
1290        // success. O_CLOEXEC ensures the fds are not leaked across
1291        // later execve calls on the parent side.
1292        let rc = unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_CLOEXEC) };
1293        if rc != 0 {
1294            return Err(std::io::Error::last_os_error());
1295        }
1296        // SAFETY: pipe2 returned success and gave us two fresh fds.
1297        let read_fd = unsafe { std::os::fd::OwnedFd::from_raw_fd(fds[0]) };
1298        let write_fd = unsafe { std::os::fd::OwnedFd::from_raw_fd(fds[1]) };
1299        Ok(Self { read_fd, write_fd })
1300    }
1301
1302    fn r_fd(&self) -> i32 {
1303        use std::os::fd::AsRawFd;
1304        self.read_fd.as_raw_fd()
1305    }
1306
1307    fn w_fd(&self) -> i32 {
1308        use std::os::fd::AsRawFd;
1309        self.write_fd.as_raw_fd()
1310    }
1311}
1312
1313/// Parent-side bundle carrying every resource the cgroup-placement
1314/// handshake needs after fork. Owned by the caller of
1315/// [`build_command`] until
1316/// [`spawn_with_cgroup_sync`] consumes it.
1317///
1318/// `notify` — the child writes its pid's bytes to the write end
1319/// as its first pre_exec step; the parent reads from the read end.
1320///
1321/// `release` — the parent writes a single byte to the write end
1322/// once the cgroup-placement update is committed; the child's
1323/// pre_exec blocks on a read of the read end.
1324///
1325/// `cgroup_name` — the user-facing cgroup name the test author
1326/// passed in `Op::RunPayload { cgroup: Some(name), .. }` or
1327/// `PayloadRun::in_cgroup(name)`. Threaded to
1328/// [`crate::cgroup::CgroupOps::place_task_during_handshake`]
1329/// at placement time so the trait implementation derives the
1330/// cgroup.procs path from its own parent-path knowledge, keeping
1331/// the host-side mock observable without touching cgroupfs.
1332///
1333/// `cgroup_procs_path` — the absolute `<cgroup>/cgroup.procs`
1334/// path, retained for diagnostic surfaces (the path appears in
1335/// trait-method `with_context` error messages so a failing
1336/// placement still names the exact filesystem path that didn't
1337/// accept the write).
1338struct CgroupSyncHandles {
1339    notify: PipePair,
1340    release: PipePair,
1341    cgroup_name: String,
1342    cgroup_procs_path: PathBuf,
1343}
1344
1345/// Async-signal-safe body of the cgroup-placement `pre_exec`
1346/// hook. Runs between fork and execve in the child.
1347///
1348/// Protocol:
1349/// 0. Close the child's inherited copies of the parent-owned
1350///    ends — `notify_read_fd` (child never reads notify) and
1351///    `release_write_fd` (child never writes release). This is
1352///    MANDATORY: without it the kernel still sees two writers on
1353///    the release pipe (parent's + child's own inherited copy),
1354///    so the parent's Drop of the release write end does NOT
1355///    deliver EOF to the child's `read(release_read_fd)` — the
1356///    child blocks forever. This is the canonical pipe-sync
1357///    fork-inherited-fd deadlock; closing the inherited copies
1358///    is what makes the sync work.
1359/// 1. Write the child's pid (as an LE i32, 4 bytes) to
1360///    `notify_write_fd` so the parent can begin the `cgroup.procs`
1361///    write. Close `notify_write_fd` immediately after so the
1362///    parent's read sees a fast EOF if the child crashes before
1363///    reaching the release read.
1364/// 2. Read a single release byte from `release_read_fd` to block
1365///    until the parent has committed the cgroup-placement write.
1366/// 3. Close `release_read_fd` (the kernel will also close it via
1367///    O_CLOEXEC on execve, but a prompt close frees the fd before
1368///    any user-provided pre_exec extension could observe it).
1369///
1370/// # Safety
1371///
1372/// This function runs between `fork(2)` and `execve(2)` in the
1373/// child. Only async-signal-safe operations are permitted — no
1374/// `malloc`, no `std::fs`, no `libc::printf`, no locks (including
1375/// the jemalloc arena). Every operation here is `getpid` / `write`
1376/// / `read` / `close`, all of which POSIX.1-2017 §2.4.3 lists as
1377/// AS-safe. In particular there is NO stdlib I/O, NO integer
1378/// formatting, and NO allocation — the pid is sent as 4 raw
1379/// little-endian bytes rather than an ASCII render, so no
1380/// formatting helper is reachable from the child side.
1381///
1382/// Errors from `write(2)` or `read(2)` (short writes, EPIPE from
1383/// a parent that abandoned the handshake) are mapped to
1384/// `io::Error::from_raw_os_error` and returned. The stdlib's
1385/// spawn loop forwards the errno through its CLOEXEC status pipe
1386/// so the parent's `spawn()` returns an actionable error rather
1387/// than silently racing through the placement step. Step 0's
1388/// `close(2)` failures are intentionally IGNORED — EBADF is
1389/// expected if the kernel is unusual about inherited fd numbering,
1390/// and any other errno here cannot be recovered from (the parent's
1391/// handshake still needs to run). The subsequent `write` / `read`
1392/// surfaces any real breakage.
1393fn cgroup_sync_pre_exec(
1394    notify_read_fd: libc::c_int,
1395    notify_write_fd: libc::c_int,
1396    release_read_fd: libc::c_int,
1397    release_write_fd: libc::c_int,
1398) -> std::io::Result<()> {
1399    // Step 0: close the child's inherited copies of the
1400    // parent-owned ends. MANDATORY to avoid deadlocking on the
1401    // subsequent `read(release_read_fd)` — without closing
1402    // `release_write_fd`, the kernel keeps the release pipe's
1403    // writer-count non-zero even when the parent drops its own
1404    // copy, so the child's read never EOFs. Symmetrically,
1405    // closing `notify_read_fd` frees a descriptor slot and keeps
1406    // the parent's notify read end the sole reader (defense in
1407    // depth — the protocol doesn't strictly require it since we
1408    // never EOF the notify pipe, but a tidy close is cheap).
1409    //
1410    // `libc::close` is AS-safe. Return codes are ignored: EBADF
1411    // is theoretically possible if the kernel ever renumbered
1412    // the inherited fd, and any other errno is non-actionable
1413    // between fork and execve. The write/read below surfaces any
1414    // real breakage.
1415    //
1416    // SAFETY: all four fd numbers were valid on the parent side
1417    // at the time of fork and the kernel duplicates them into
1418    // the child's fd table. Closing a fd that the kernel already
1419    // renumbered returns EBADF without effect — no memory
1420    // safety concern.
1421    unsafe {
1422        libc::close(notify_read_fd);
1423        libc::close(release_write_fd);
1424    }
1425
1426    // Step 1: publish pid. getpid(2) is AS-safe; the pid is a
1427    // raw i32, so we send its 4-byte little-endian encoding and
1428    // spare the child any integer-formatting work. A stack
1429    // buffer is the only storage; no allocation.
1430    let pid = unsafe { libc::getpid() };
1431    let pid_bytes = pid.to_le_bytes();
1432    let mut written = 0usize;
1433    while written < pid_bytes.len() {
1434        // SAFETY: writing into a raw fd that the parent owns the
1435        // read end of. `pid_bytes` is a live stack buffer.
1436        let n = unsafe {
1437            libc::write(
1438                notify_write_fd,
1439                pid_bytes.as_ptr().add(written) as *const libc::c_void,
1440                pid_bytes.len() - written,
1441            )
1442        };
1443        if n < 0 {
1444            let err = std::io::Error::last_os_error();
1445            // EINTR: retry. Every other errno (EPIPE from a
1446            // collapsed parent read end, EBADF, ...) is terminal
1447            // — surface it to the parent via the stdlib spawn
1448            // error channel.
1449            if err.raw_os_error() == Some(libc::EINTR) {
1450                continue;
1451            }
1452            return Err(err);
1453        }
1454        if n == 0 {
1455            // Zero-byte write is not defined for pipes; treat as
1456            // EIO rather than loop forever.
1457            return Err(std::io::Error::from_raw_os_error(libc::EIO));
1458        }
1459        written += n as usize;
1460    }
1461    // Close the notify write end so the parent's read gets EOF if
1462    // the child subsequently crashes before the release read.
1463    // SAFETY: notify_write_fd is a valid fd the child inherited
1464    // from the parent; closing it here does not affect the parent's
1465    // read end.
1466    unsafe {
1467        libc::close(notify_write_fd);
1468    }
1469
1470    // Step 2: block on the release byte. One byte is enough — the
1471    // payload is a synchronization token, not data. Loop to handle
1472    // EINTR and short reads (partial-byte reads are impossible on
1473    // a 1-byte read, but the loop keeps the code uniform with the
1474    // write side).
1475    let mut buf = [0u8; 1];
1476    let mut read_total = 0usize;
1477    while read_total < buf.len() {
1478        // SAFETY: reading from a raw fd that the parent owns the
1479        // write end of. `buf` is a live stack buffer.
1480        let n = unsafe {
1481            libc::read(
1482                release_read_fd,
1483                buf.as_mut_ptr().add(read_total) as *mut libc::c_void,
1484                buf.len() - read_total,
1485            )
1486        };
1487        if n < 0 {
1488            let err = std::io::Error::last_os_error();
1489            if err.raw_os_error() == Some(libc::EINTR) {
1490                continue;
1491            }
1492            return Err(err);
1493        }
1494        if n == 0 {
1495            // EOF before the release byte arrived — the parent
1496            // abandoned the handshake (crashed / failed cgroup
1497            // write). Fail the pre_exec so the stdlib spawn path
1498            // surfaces the abort instead of letting the child
1499            // execve into an unplaced cgroup.
1500            return Err(std::io::Error::from_raw_os_error(libc::EPIPE));
1501        }
1502        read_total += n as usize;
1503    }
1504    // Step 3: close the release read end. The kernel would do
1505    // this on execve via O_CLOEXEC anyway, but an explicit close
1506    // frees the fd now.
1507    // SAFETY: release_read_fd is a valid fd the child inherited
1508    // from the parent.
1509    unsafe {
1510        libc::close(release_read_fd);
1511    }
1512    Ok(())
1513}
1514
1515/// Complete the cgroup-placement handshake on a child that was
1516/// spawned with a [`build_command`]-supplied pre_exec hook.
1517///
1518/// The caller MUST run `Command::spawn()` on a dedicated thread
1519/// because the stdlib's `spawn()` blocks on its CLOEXEC status
1520/// pipe until the child has successfully execve'd — and the
1521/// child's pre_exec blocks on the release read until this
1522/// function finishes. Without the thread split the two would
1523/// deadlock.
1524///
1525/// Protocol (parent side, main thread):
1526/// 1. Read the child's pid bytes from the notify read end.
1527/// 2. Dispatch placement via
1528///    [`crate::cgroup::CgroupOps::place_task_during_handshake`],
1529///    threading the user-facing `cgroup_name` and the just-read
1530///    child pid. The trait implementation
1531///    ([`crate::cgroup::CgroupManager::place_task_during_handshake`]
1532///    in production) derives the `cgroup.procs` path from its own
1533///    parent-path knowledge and performs the write under the same
1534///    `write_with_timeout` shape as the other cgroupfs writes;
1535///    `MockCgroupOps` records the call without touching the
1536///    filesystem so handler-level tests can observe placement
1537///    against `Op::RunPayload { cgroup: Some(..), .. }`.
1538/// 3. Write the single release byte to the release write end,
1539///    then close it so any subsequent short-read / EOF on the
1540///    child side is prompt.
1541/// 4. Close the notify read end.
1542///
1543/// The function returns the child pid so callers can cross-check
1544/// it against `Child::id()` once the spawn thread returns.
1545/// Wrapped in `Result<libc::pid_t>` because the notify read or
1546/// the placement trait call can fail; a failure drops the
1547/// handle, which also closes the release write end, giving the
1548/// child's pre_exec a fast EOF-driven bail (the trait contract
1549/// pins this responsibility on the caller — see
1550/// [`crate::cgroup::CgroupOps::place_task_during_handshake`]).
1551fn spawn_with_cgroup_sync(
1552    handles: CgroupSyncHandles,
1553    cgroup_ops: &dyn crate::cgroup::CgroupOps,
1554) -> Result<libc::pid_t> {
1555    use std::io::{Read, Write};
1556    let CgroupSyncHandles {
1557        notify,
1558        release,
1559        cgroup_name,
1560        cgroup_procs_path,
1561    } = handles;
1562    // Step 1: read child pid. Keep the parent-side notify_w
1563    // OPEN during the read — closing it before fork would let
1564    // stdlib's internal `pipe2` for the CLOEXEC status pipe
1565    // recycle our fd number; the child then inherits a state
1566    // where its `notify_write_fd` points at stdlib's status
1567    // pipe, not our notify pipe. `write(notify_write_fd, pid)`
1568    // in the child would corrupt stdlib's protocol and the
1569    // parent's `read_exact` on our notify pipe would see an
1570    // indefinite wait because no data ever arrives on the
1571    // intended pipe. The canonical rule: drop your parent
1572    // copy of the child's write end AFTER the child has
1573    // written (or died), not before. We achieve that here by
1574    // holding `notify_w` alive across the read and dropping
1575    // it only at the end.
1576    //
1577    // Child-died-without-writing detection: if the child
1578    // dies before step 1's write, its inherited `notify_w`
1579    // closes on `_exit`. The pipe then has ONLY the parent's
1580    // `notify_w` as a writer — still non-zero — and our
1581    // `read_exact` would block indefinitely. Guard against
1582    // that with a bounded `poll(2)`: wait up to 5s for data,
1583    // then bail with an actionable error naming the
1584    // probable cause (child pre_exec failed before writing).
1585    // The spawn thread's own error (`cmd.spawn() → Err`)
1586    // surfaces too, and `drive_cgroup_handshake` returns
1587    // whichever the caller sees first.
1588    let PipePair {
1589        read_fd: notify_r,
1590        write_fd: notify_w,
1591    } = notify;
1592    {
1593        let pfd_fd = std::os::fd::AsRawFd::as_raw_fd(&notify_r);
1594        let mut pfd = libc::pollfd {
1595            fd: pfd_fd,
1596            events: libc::POLLIN,
1597            revents: 0,
1598        };
1599        // 5s ceiling. Any legitimate fork + pre_exec sequence
1600        // completes in low milliseconds; 5s is loose for even
1601        // the most contended CI host and tight enough to
1602        // flag a silent child-death promptly.
1603        let poll_ms: libc::c_int = 5_000;
1604        let ready = unsafe { libc::poll(&mut pfd, 1, poll_ms) };
1605        if ready < 0 {
1606            let e = std::io::Error::last_os_error();
1607            if e.raw_os_error() != Some(libc::EINTR) {
1608                return Err(
1609                    anyhow::Error::new(e).context("poll(notify_r) for cgroup-sync pid-notify")
1610                );
1611            }
1612        } else if ready == 0 {
1613            anyhow::bail!(
1614                "cgroup-sync notify pipe: no pid written by child within 5s. \
1615                 The child's pre_exec likely failed before Step 1 (possibly \
1616                 EBADF on `notify_write_fd` because the fd number was \
1617                 recycled by stdlib's internal pipe2). Check the spawn \
1618                 thread's error for the underlying cause."
1619            );
1620        }
1621    }
1622    let mut notify_file = std::fs::File::from(notify_r);
1623    let mut pid_bytes = [0u8; 4];
1624    notify_file
1625        .read_exact(&mut pid_bytes)
1626        .context("read child pid from cgroup-sync notify pipe")?;
1627    drop(notify_file);
1628    // Now it is safe to close parent's notify write end:
1629    // the child has either written its pid (success path) or
1630    // the poll bailed (failure path, already returned above).
1631    drop(notify_w);
1632    let child_pid = libc::pid_t::from_le_bytes(pid_bytes);
1633    anyhow::ensure!(
1634        child_pid > 0,
1635        "cgroup-sync notify pipe returned non-positive pid {child_pid}; \
1636         the child's pre_exec hook sent a corrupted pid — fail the \
1637         handshake rather than write a bad value to cgroup.procs"
1638    );
1639
1640    // Step 2: dispatch placement through the CgroupOps trait so
1641    // the production write goes through `CgroupManager` and the
1642    // test path's `MockCgroupOps` records the placement for
1643    // handler-level observability. The trait implementation
1644    // derives the cgroup.procs path from its own parent-path
1645    // knowledge; `cgroup_procs_path` is held alongside
1646    // `cgroup_name` purely so the error chain still names the
1647    // path that didn't accept the write. We are on the parent's
1648    // main thread post-fork — no AS-safety constraint applies,
1649    // so the trait dispatch's heap allocations and anyhow error
1650    // chain are fair game (pre_exec runs on the CHILD side and
1651    // never reaches this branch).
1652    cgroup_ops
1653        .place_task_during_handshake(&cgroup_name, child_pid)
1654        .with_context(|| {
1655            format!(
1656                "place pid {child_pid} into cgroup '{cgroup_name}' (cgroup.procs at {}) for cgroup-sync placement",
1657                cgroup_procs_path.display(),
1658            )
1659        })?;
1660
1661    // Step 3: release the child. One byte is enough; the content
1662    // is ignored by the reader.
1663    let PipePair {
1664        read_fd: release_r,
1665        write_fd: release_w,
1666    } = release;
1667    drop(release_r);
1668    let mut release_file = std::fs::File::from(release_w);
1669    release_file
1670        .write_all(&[1u8])
1671        .context("write release byte to cgroup-sync release pipe")?;
1672    drop(release_file);
1673
1674    Ok(child_pid)
1675}
1676
1677/// Spawn a Command that carries a cgroup-sync pre_exec hook.
1678/// Runs `Command::spawn()` on a dedicated thread (it blocks on
1679/// the stdlib CLOEXEC status pipe until the child execve's,
1680/// which can't happen until the parent's main thread has
1681/// released the pre_exec handshake), drives the
1682/// [`spawn_with_cgroup_sync`] protocol on the main thread, then
1683/// joins the spawn thread to collect the resulting [`std::process::Child`].
1684///
1685/// If either the spawn or the handshake fails, the caller drops
1686/// the remaining pipe handles (via the [`CgroupSyncHandles`]
1687/// consumption in `spawn_with_cgroup_sync`), which causes the
1688/// child's pre_exec read to unblock with EOF and fail with
1689/// EPIPE. The child never reaches execve, the spawn thread
1690/// surfaces the pre_exec error through its stdlib error
1691/// channel, and we propagate the first error the caller sees.
1692fn drive_cgroup_handshake(
1693    cmd: std::process::Command,
1694    handles: CgroupSyncHandles,
1695    binary: &str,
1696    cgroup_ops: &dyn crate::cgroup::CgroupOps,
1697) -> Result<std::process::Child> {
1698    // Move the Command into a thread so its blocking `spawn()`
1699    // doesn't deadlock with the child's pre_exec handshake.
1700    let binary_owned = binary.to_string();
1701    let spawn_thread = std::thread::spawn(move || -> Result<std::process::Child> {
1702        let mut cmd = cmd;
1703        cmd.spawn()
1704            .map_err(|e| spawn_error_context(e, &binary_owned))
1705    });
1706
1707    // Drive the placement protocol on the main thread. If this
1708    // fails we drop the remaining handle bits so the child sees
1709    // EOF on its release read; the spawn thread will then
1710    // surface the pre_exec EPIPE through its stdlib error
1711    // channel.
1712    let sync_result = spawn_with_cgroup_sync(handles, cgroup_ops);
1713
1714    // Join the spawn thread regardless of sync outcome so a
1715    // failing handshake does not leak a background std thread.
1716    // A join error is either a panic in the spawn closure (very
1717    // rare under `panic = "unwind"`) or an explicit poisoning;
1718    // we map it to a generic anyhow error so the caller still
1719    // gets a meaningful chain.
1720    let spawn_result = spawn_thread
1721        .join()
1722        .map_err(|_| anyhow!("cgroup-sync spawn thread panicked"))?;
1723
1724    // Precedence: if the sync failed, that error is the root
1725    // cause (the spawn will have failed TOO because the child
1726    // bailed on EPIPE, but the sync error carries the actionable
1727    // diagnostic — "failed to open cgroup.procs" / "short read
1728    // from notify pipe"). Return the sync error first and
1729    // discard the spawn error.
1730    sync_result?;
1731    spawn_result
1732}
1733
1734/// Actionable error wrapper for Command::spawn/.output failures.
1735/// ENOENT — the binary isn't on PATH inside the guest — gets the
1736/// remediation paths spelled out: `-i`/`--include-files` for CLI
1737/// invocations, pre-install in the initramfs for `#[ktstr_test]`
1738/// entries (which cannot pass `-i`). Other errors keep the minimal
1739/// `"spawn '<binary>'"` context so the underlying io::Error chain
1740/// surfaces unchanged.
1741///
1742/// **Shebang interpreter case.** `execve(2)` ALSO returns ENOENT
1743/// when `binary` is itself present but is a script whose `#!`
1744/// shebang names an interpreter that is missing in the guest
1745/// (e.g. `#!/usr/bin/python3` when python3 is absent from
1746/// initramfs). The kernel surfaces ENOENT with the script's path
1747/// even though the missing file is the interpreter — there is no
1748/// userspace signal that distinguishes "binary missing" from
1749/// "interpreter missing". The wrapped message therefore names
1750/// both the binary and the interpreter as candidate missing
1751/// artifacts and tells the operator to package both with `-i`
1752/// (CLI) or pre-install both in the initramfs
1753/// (`#[ktstr_test]`); the production message body carries this
1754/// guidance verbatim, the test
1755/// `spawn_error_context_enoent_attaches_remediation` pins it.
1756fn spawn_error_context(err: std::io::Error, binary: &str) -> anyhow::Error {
1757    if err.kind() == std::io::ErrorKind::NotFound {
1758        anyhow::Error::new(err).context(format!(
1759            "spawn '{binary}': binary not found on guest PATH. \
1760             Remediation: for CLI invocations (ktstr / cargo-ktstr \
1761             shell, run, …), package the binary with `-i {binary}` \
1762             / `--include-files {binary}` so it lands on the guest \
1763             PATH under `/include-files/`. For `#[ktstr_test]` \
1764             entries, pre-install the binary in the base initramfs \
1765             — the macro surface does not expose `-i`. If `{binary}` \
1766             is a script, execve(2) ALSO returns ENOENT when the \
1767             `#!` shebang names an interpreter missing from the \
1768             guest (the error names the script but the missing \
1769             file is the interpreter); package the interpreter \
1770             the same way — `-i <interpreter>` for CLI, pre-install \
1771             for `#[ktstr_test]`."
1772        ))
1773    } else {
1774        anyhow::Error::new(err).context(format!("spawn '{binary}'"))
1775    }
1776}
1777
1778/// RAII guard that saves the process's `SIGCHLD` disposition, sets
1779/// it to `SIG_DFL` on construction, and restores the saved value on
1780/// `Drop`. Required for [`spawn_and_wait`] and the background
1781/// [`spawn_child`] path because the guest ktstr-init sets
1782/// `SIGCHLD = SIG_IGN` at startup in `src/vmm/rust_init/init.rs`
1783/// ("Ignore SIGCHLD so child processes don't become zombies").
1784/// Under `SIG_IGN` the kernel auto-reaps children, so
1785/// `waitpid(child_pid)` returns `ECHILD` and Rust std's
1786/// `Command::spawn()` / `.output()` / `Child::wait()` internals
1787/// panic with "wait() should either return Ok or panic".
1788///
1789/// The shell-exec mode in `src/vmm/rust_init/modes.rs` already documents
1790/// this exact gotcha and uses the same save/set-`SIG_DFL` /
1791/// restore-on-completion pattern. `PayloadRun::run` /
1792/// `PayloadRun::spawn` are the second dispatch site that needs it.
1793///
1794/// For background spawns, the guard lives on [`PayloadHandle`]
1795/// until `.wait()` / `.kill()` / `Drop` consumes the handle, so
1796/// the child is reap-able via `waitpid` for the entire window
1797/// between spawn and final disposition. Foreground spawns
1798/// (`spawn_and_wait`) scope the guard to the `.output()` call —
1799/// the child is reaped inline, no lingering state.
1800/// Pins the [`ThreadId`] of the first `SigchldScope` constructed in
1801/// this process. Every subsequent construction must come from the
1802/// same thread: `libc::signal` is not thread-safe, and concurrent
1803/// installs from distinct threads would race on the process-wide
1804/// `SIGCHLD` disposition. The unset state of the `OnceLock` means
1805/// "uninitialized" (no `SigchldScope` has been constructed yet in
1806/// this process).
1807///
1808/// `ThreadId` is the std-library opaque thread identifier with
1809/// guaranteed uniqueness for the lifetime of the process and a
1810/// `PartialEq` impl that compares the underlying `NonZero<u64>`
1811/// directly. Storing the actual `ThreadId` (instead of a hash of
1812/// it) eliminates the collision-window risk that any hash-based
1813/// encoding carries, no matter how astronomically unlikely.
1814///
1815/// Multiple concurrent `SigchldScope` instances ARE allowed on
1816/// the same thread — each `PayloadHandle` carries one, and a
1817/// single-threaded caller can hold many handles simultaneously
1818/// without racing the libc::signal install. Drop order must
1819/// remain LIFO for the handler-restore chain to leave the
1820/// original disposition intact; this is the caller's obligation
1821/// (handles dropped in reverse creation order, which is the
1822/// default when locals go out of scope).
1823static SIGCHLD_SCOPE_OWNER_THREAD: OnceLock<ThreadId> = OnceLock::new();
1824
1825struct SigchldScope {
1826    prev: libc::sighandler_t,
1827    /// Marker that makes `SigchldScope` `!Send` AND `!Sync` at the
1828    /// type-system level. `libc::sighandler_t` is `size_t` on Linux
1829    /// (a plain integer that auto-implements both `Send` and `Sync`),
1830    /// so without this marker the struct would be `Send + Sync` and
1831    /// the compiler would silently accept a move across thread
1832    /// boundaries. The `OnceLock`-based runtime pin in `new` and
1833    /// `drop` only catches an actual install/restore on the wrong
1834    /// thread; the `PhantomData<*const ()>` adds a compile-time
1835    /// barrier so a `thread::spawn(move || { let _ = scope; })`
1836    /// fails to type-check instead of relying on the runtime check
1837    /// to catch it.
1838    ///
1839    /// `*const T` carries explicit `!Send` and `!Sync` negative
1840    /// impls in `core::marker` (`impl<T: PointeeSized> !Send for
1841    /// *const T` at marker.rs:100, `impl<T: PointeeSized> !Sync for
1842    /// *const T` at marker.rs:680). `Send` and `Sync` are
1843    /// independent auto traits — neither implies the other — and
1844    /// `PhantomData<T>` (a generic struct with no manual Send/Sync
1845    /// impl) propagates each independently via auto-trait
1846    /// inference. So `PhantomData<*const ()>` is `!Send` because
1847    /// `*const ()` is `!Send`, AND `!Sync` because `*const ()` is
1848    /// `!Sync`. Both come from the marker, not from one implying
1849    /// the other.
1850    _not_send: std::marker::PhantomData<*const ()>,
1851}
1852
1853impl SigchldScope {
1854    /// Save current `SIGCHLD` handler and install `SIG_DFL`.
1855    /// On host builds the init never flips SIGCHLD to SIG_IGN, so
1856    /// `prev` equals `SIG_DFL` and Drop is a no-op mathematically
1857    /// — the extra syscall is cheap and keeps behavior uniform
1858    /// between host and guest.
1859    ///
1860    /// # Panics
1861    ///
1862    /// Panics if called from a thread different from the one that
1863    /// constructed the first `SigchldScope` in this process.
1864    /// `libc::signal` is not thread-safe and cross-thread installs
1865    /// would race on the process-wide SIGCHLD disposition.
1866    fn new() -> Self {
1867        let tid = std::thread::current().id();
1868        // Pin the first thread that ever constructs a SigchldScope
1869        // in this process via `OnceLock::get_or_init`, then enforce
1870        // the pin on every subsequent construction. `get_or_init`
1871        // is internally synchronized: concurrent first-callers
1872        // race only on which one's `init` closure runs, and the
1873        // others observe the winner's value via the same call. The
1874        // returned reference is the canonical pinned ThreadId.
1875        let pinned = SIGCHLD_SCOPE_OWNER_THREAD.get_or_init(|| tid);
1876        if *pinned != tid {
1877            panic!(
1878                "SigchldScope constructed on a different thread than the first \
1879                 owner (pinned thread id={pinned:?}, this thread's id={tid:?}). \
1880                 libc::signal is not thread-safe; cross-thread installs race on \
1881                 the process-wide SIGCHLD disposition."
1882            );
1883        }
1884        // SAFETY: SIGCHLD_SCOPE_OWNER_THREAD pins construction to
1885        // a single thread across the whole process, so no other
1886        // thread is concurrently installing a SIGCHLD handler.
1887        // The `_not_send: PhantomData<*const ()>` field below makes
1888        // the type `!Send` so a move across threads fails to compile
1889        // — Drop is guaranteed to run on the same thread that
1890        // constructed the scope.
1891        let prev = unsafe { libc::signal(libc::SIGCHLD, libc::SIG_DFL) };
1892        SigchldScope {
1893            prev,
1894            _not_send: std::marker::PhantomData,
1895        }
1896    }
1897}
1898
1899impl Drop for SigchldScope {
1900    fn drop(&mut self) {
1901        // Defense-in-depth: the `!Send` marker on the struct
1902        // prevents a compile-time cross-thread move, but a future
1903        // refactor that adds an explicit `unsafe impl Send`
1904        // workaround would silently bypass that guard. Re-check the
1905        // owner-thread pin at drop time so a wrong-thread restore
1906        // panics loudly instead of quietly racing the process-wide
1907        // SIGCHLD disposition.
1908        let pinned = SIGCHLD_SCOPE_OWNER_THREAD
1909            .get()
1910            .expect("SIGCHLD_SCOPE_OWNER_THREAD must be initialized — set by SigchldScope::new");
1911        assert_eq!(
1912            *pinned,
1913            std::thread::current().id(),
1914            "SigchldScope dropped on a different thread than the pinned owner \
1915             (pinned={pinned:?}, this thread={:?}). libc::signal is not \
1916             thread-safe and the construct-side `!Send` marker should have \
1917             made this impossible at compile time — investigate any \
1918             `unsafe impl Send for SigchldScope` that bypassed it.",
1919            std::thread::current().id(),
1920        );
1921        // SAFETY: same rationale as `new` — the owner-thread pin
1922        // guarantees no concurrent installer on another thread.
1923        // Restoring in LIFO order across nested scopes unwinds
1924        // back to the original disposition; drop-order is the
1925        // caller's obligation.
1926        unsafe {
1927            libc::signal(libc::SIGCHLD, self.prev);
1928        }
1929    }
1930}
1931
1932// Compile-time pin: `SigchldScope` must be neither `Send` nor `Sync`.
1933//
1934// `SigchldScope::new` and its `Drop` install/restore the process-wide
1935// `SIGCHLD` disposition via `libc::signal`, which is documented as
1936// async-signal-safe but not thread-safe with respect to concurrent
1937// installs. The `_not_send: PhantomData<*const ()>` field at the
1938// struct definition is what makes the type `!Send` AND `!Sync`.
1939// `Send` and `Sync` are independent auto traits — neither implies
1940// the other. `*const T` carries explicit `!Send` and `!Sync`
1941// negative impls in `core::marker` (`impl<T: PointeeSized> !Send
1942// for *const T` at marker.rs:100, `impl<T: PointeeSized> !Sync for
1943// *const T` at marker.rs:680), and `PhantomData<T>` propagates each
1944// independently via auto-trait inference. So `PhantomData<*const
1945// ()>` is `!Send` because `*const ()` is `!Send`, AND `!Sync`
1946// because `*const ()` is `!Sync` — both from the marker, not from
1947// one implying the other. This block re-asserts that invariant at
1948// compile time so a future refactor that drops the marker, replaces
1949// it with a `Send` type, or adds an explicit `unsafe impl
1950// Send`/`unsafe impl Sync` for `SigchldScope` fails to compile here
1951// instead of silently allowing a cross-thread move that would race
1952// the SIGCHLD install on another thread.
1953//
1954// Mechanism (mirrors `static_assertions::assert_not_impl_any!`): a
1955// blanket `AmbiguousIfImpl<()>` impl applies to every type, while a
1956// specialized `AmbiguousIfImpl<Invalid{Send,Sync}>` impl applies only
1957// to types that `Send` / `Sync` respectively. If `SigchldScope`
1958// implemented either, two impls would match `AmbiguousIfImpl<_>` and
1959// type inference for `_` would be ambiguous, producing a compile
1960// error. With `SigchldScope: !Send + !Sync`, only the blanket impl
1961// matches and the assertion compiles.
1962//
1963// `static_assertions` is a transitive dep (via `compact_str`) but not
1964// a direct dependency; inlining the trick keeps the assertion local
1965// without growing the direct dep graph for one use site.
1966const _: fn() = || {
1967    trait AmbiguousIfImpl<A> {
1968        fn some_item() {}
1969    }
1970    impl<T: ?Sized> AmbiguousIfImpl<()> for T {}
1971
1972    #[allow(dead_code)]
1973    struct InvalidSend;
1974    impl<T: ?Sized + Send> AmbiguousIfImpl<InvalidSend> for T {}
1975
1976    #[allow(dead_code)]
1977    struct InvalidSync;
1978    impl<T: ?Sized + Sync> AmbiguousIfImpl<InvalidSync> for T {}
1979
1980    let _ = <SigchldScope as AmbiguousIfImpl<_>>::some_item;
1981};
1982
1983/// Foreground path: spawn + wait + capture. Used by `.run()`.
1984///
1985/// Wraps the child's lifetime in a [`SigchldScope`] so `waitpid`
1986/// sees `SIG_DFL` and returns the child's real exit status instead
1987/// of `ECHILD` under the guest init's `SIGCHLD = SIG_IGN`.
1988///
1989/// When `timeout` is `Some`, a poll loop bounds the payload's
1990/// runtime. Exceeding the deadline fires
1991/// [`kill_payload_process_group`] (killpg + single-pid SIGKILL)
1992/// so fork descendants die and release the pipes, then
1993/// [`wait_and_capture`] drains whatever output accumulated before
1994/// the kill. The `SpawnOutput` returned on timeout carries the
1995/// partial output and the post-kill exit code; the caller decides
1996/// whether that counts as a test failure.
1997fn spawn_and_wait(
1998    binary: &str,
1999    args: &[String],
2000    cgroup: Option<(&str, &std::path::Path)>,
2001    timeout: Option<Duration>,
2002    uses_parent_pgrp: bool,
2003    cgroup_ops: &dyn crate::cgroup::CgroupOps,
2004) -> Result<SpawnOutput> {
2005    let _sigchld = SigchldScope::new();
2006    let (cmd, sync_handles) = build_command(binary, args, cgroup, uses_parent_pgrp)?;
2007    let mut child = match sync_handles {
2008        Some(handles) => drive_cgroup_handshake(cmd, handles, binary, cgroup_ops)?,
2009        None => {
2010            let mut cmd = cmd;
2011            cmd.spawn().map_err(|e| spawn_error_context(e, binary))?
2012        }
2013    };
2014    match timeout {
2015        Some(deadline) => wait_with_deadline(&mut child, deadline, binary, uses_parent_pgrp),
2016        None => match wait_and_capture(&mut child) {
2017            Ok(out) => Ok(out),
2018            Err(e) => {
2019                kill_payload_process_group(&child, binary, uses_parent_pgrp);
2020                let _ = child.wait();
2021                Err(e)
2022            }
2023        },
2024    }
2025}
2026
2027/// Block in the kernel until the child exits or `timeout` elapses.
2028/// On expiry, kill the whole process group (killpg + single-pid
2029/// SIGKILL) and drain captured output.
2030///
2031/// Implementation uses `pidfd_open(2)` + `epoll_wait` so the waiter
2032/// is kernel-blocked instead of spinning on a 10ms `try_wait` loop.
2033/// The earlier poll burned one wake per 10ms for the entire payload
2034/// runtime (typically multi-second schbench / fio runs), producing a
2035/// small but measurable CPU spike on every timed payload; pidfd
2036/// parks the thread until the kernel signals child exit, so idle
2037/// waiters contribute zero CPU. Minimum kernel: Linux 5.3.
2038///
2039/// Deadline honoring: the `epoll_wait` timeout is re-derived from
2040/// `saturating_duration_since` each iteration so `EINTR` restarts
2041/// narrow the remaining window rather than extending it.
2042fn wait_with_deadline(
2043    child: &mut std::process::Child,
2044    timeout: Duration,
2045    payload_name: &str,
2046    uses_parent_pgrp: bool,
2047) -> Result<SpawnOutput> {
2048    use nix::sys::epoll::{Epoll, EpollCreateFlags, EpollEvent, EpollFlags, EpollTimeout};
2049    use std::os::fd::{AsFd, FromRawFd, OwnedFd};
2050
2051    let deadline = std::time::Instant::now() + timeout;
2052
2053    let pid =
2054        libc::pid_t::try_from(child.id()).expect("child pid fits in pid_t (Linux pid_max <= 2^22)");
2055    // `pidfd_open(pid, 0)`: returns an fd that becomes readable when
2056    // the pid exits. No `PIDFD_NONBLOCK` flag — epoll is the gate.
2057    let pidfd_raw = unsafe { libc::syscall(libc::SYS_pidfd_open, pid, 0i32) };
2058    if pidfd_raw < 0 {
2059        return Err(std::io::Error::last_os_error()).with_context(|| format!("pidfd_open({pid})"));
2060    }
2061    // SAFETY: the syscall succeeded and returned a fresh fd.
2062    let pidfd: OwnedFd = unsafe { OwnedFd::from_raw_fd(pidfd_raw as i32) };
2063
2064    let epoll = Epoll::new(EpollCreateFlags::EPOLL_CLOEXEC)
2065        .with_context(|| "epoll_create1 for pidfd wait")?;
2066    // `data` field is unused — we only ever watch one fd. The add()
2067    // syscall still needs an `EpollEvent` with populated events.
2068    let event = EpollEvent::new(EpollFlags::EPOLLIN, 0);
2069    epoll
2070        .add(pidfd.as_fd(), event)
2071        .with_context(|| "epoll_ctl ADD pidfd")?;
2072
2073    let mut events = [EpollEvent::empty()];
2074    loop {
2075        // Race-safe reap attempt first: if the child exited between
2076        // spawn and pidfd_open, or between iterations while we were
2077        // outside epoll_wait, `try_wait` catches it without a needless
2078        // syscall.
2079        if child
2080            .try_wait()
2081            .with_context(|| "try_wait child")?
2082            .is_some()
2083        {
2084            return match wait_and_capture(child) {
2085                Ok(out) => Ok(out),
2086                Err(e) => {
2087                    kill_payload_process_group(child, payload_name, uses_parent_pgrp);
2088                    let _ = child.wait();
2089                    Err(e)
2090                }
2091            };
2092        }
2093
2094        let remaining = deadline.saturating_duration_since(std::time::Instant::now());
2095        if remaining.is_zero() {
2096            kill_payload_process_group(child, payload_name, uses_parent_pgrp);
2097            return match wait_and_capture(child) {
2098                Ok(out) => Ok(out),
2099                Err(e) => {
2100                    let _ = child.wait();
2101                    Err(e).with_context(|| format!("drain after timeout of {timeout:?}"))
2102                }
2103            };
2104        }
2105
2106        // `PollTimeout` (aliased as `EpollTimeout`) stores the value
2107        // as `i32`, so `TryFrom<u32>` rejects any input larger than
2108        // `i32::MAX` (~24.8 days of milliseconds). Clamp both casts —
2109        // `u128 → u32` and then `u32 → i32`-range — so a
2110        // `Duration::MAX`-shaped remainder saturates to the max
2111        // accepted value instead of bubbling up a conversion error.
2112        let ms_u32 = u32::try_from(remaining.as_millis()).unwrap_or(u32::MAX);
2113        let ms_u32 = std::cmp::min(ms_u32, i32::MAX as u32);
2114        let timeout_param =
2115            EpollTimeout::try_from(ms_u32).with_context(|| "epoll timeout conversion")?;
2116
2117        match epoll.wait(&mut events, timeout_param) {
2118            Ok(_) => {
2119                // Either the pidfd went readable (child exit) OR the
2120                // timeout fired (ready_count == 0). Loop back: the
2121                // `try_wait` at top handles the exit path, the
2122                // `remaining.is_zero()` branch handles the deadline.
2123            }
2124            Err(nix::errno::Errno::EINTR) => {
2125                // Signal interrupted the wait; loop and re-compute
2126                // the remaining window.
2127            }
2128            Err(e) => {
2129                return Err(anyhow::anyhow!("epoll_wait: {e}"));
2130            }
2131        }
2132    }
2133}
2134
2135/// Background path: spawn without waiting. Returns the live
2136/// [`std::process::Child`] plus a [`SigchldScope`] that must be held for the
2137/// child's lifetime — [`PayloadHandle`] keeps it alive until
2138/// `.wait()` / `.kill()` / `Drop` so `waitpid` during reap sees
2139/// `SIG_DFL` and observes the child's real exit.
2140fn spawn_child(
2141    binary: &str,
2142    args: &[String],
2143    cgroup: Option<(&str, &std::path::Path)>,
2144    uses_parent_pgrp: bool,
2145    cgroup_ops: &dyn crate::cgroup::CgroupOps,
2146) -> Result<(std::process::Child, SigchldScope)> {
2147    let sigchld = SigchldScope::new();
2148    let (cmd, sync_handles) = build_command(binary, args, cgroup, uses_parent_pgrp)?;
2149    let child = match sync_handles {
2150        Some(handles) => drive_cgroup_handshake(cmd, handles, binary, cgroup_ops)?,
2151        None => {
2152            let mut cmd = cmd;
2153            cmd.spawn().map_err(|e| spawn_error_context(e, binary))?
2154        }
2155    };
2156    Ok((child, sigchld))
2157}
2158
2159/// Per-stream cap on captured child output. 16 MiB covers every
2160/// realistic benchmark stdout in the crate (typical schbench /
2161/// stress-ng flows emit kilobytes to low-hundreds-of-KB)
2162/// with multiple orders of magnitude of slack, while cutting off
2163/// OOM pressure from a pathological payload that prints unbounded
2164/// GBs. Output past the cap is truncated, not errored, so downstream
2165/// (metric extraction, sidecar) still sees a prefix — the only loss
2166/// is the tail, which is rarely load-bearing. Each truncation emits
2167/// a paired `eprintln!` + `tracing::warn!` notice naming the stream
2168/// and the cap byte count.
2169pub(crate) const MAX_CAPTURED_STREAM_BYTES: u64 = 16 * 1024 * 1024;
2170
2171/// Reap a (possibly already-killed) [`std::process::Child`]: wait for it to
2172/// exit, drain stdout + stderr, return the captured output.
2173///
2174/// Takes `&mut Child` so callers retain ownership and can
2175/// `kill_payload_process_group` + `wait` to clean up descendants
2176/// when this function returns `Err` (e.g. a reader thread panicked
2177/// or the wait syscall itself failed). An owned-child signature
2178/// would lose the handle inside this function and leave descendants
2179/// running because `std::process::Child`'s `Drop` is a no-op.
2180///
2181/// Sequential stdout-then-stderr reads deadlock when the child
2182/// fills one pipe buffer (typically 64KiB) while the other is
2183/// unread — the child blocks on write, the parent blocks on read
2184/// of the empty pipe. Drain both pipes concurrently via helper
2185/// threads, mirroring what `std::process::Command::output` does
2186/// for the foreground path.
2187///
2188/// Each reader thread wraps its source in
2189/// `Read::take(MAX_CAPTURED_STREAM_BYTES)` — see the constant's
2190/// rationale — so a runaway child cannot OOM the host. The tail
2191/// past the cap is discarded; the metric-extraction pipeline
2192/// always receives a bounded buffer.
2193fn wait_and_capture(child: &mut std::process::Child) -> Result<SpawnOutput> {
2194    let stdout_handle = child.stdout.take().map(|out| {
2195        std::thread::spawn(move || -> std::io::Result<(String, bool)> {
2196            drain_capped(out, "stdout")
2197        })
2198    });
2199    let stderr_handle = child.stderr.take().map(|err| {
2200        std::thread::spawn(move || -> std::io::Result<(String, bool)> {
2201            drain_capped(err, "stderr")
2202        })
2203    });
2204    let status = child.wait().with_context(|| "wait child")?;
2205    // `.join().unwrap()` below is NOT a bug: the workspace builds
2206    // with `panic = "abort"` in release (see Cargo.toml
2207    // `[profile.release]`), so a panicked reader thread aborts the
2208    // whole process and `join()` never returns an
2209    // `Err(Box<dyn Any + Send>)` (`std::thread::Result::Err`). The
2210    // historic `.map_err(|_| anyhow!("...panicked"))` arm could not
2211    // fire and misled readers into expecting a recoverable error.
2212    //
2213    // Under cargo's default `panic = "unwind"` (which the dev and
2214    // test profiles both inherit — only `[profile.release]` flips
2215    // to abort in this crate), a reader-thread panic DOES unwind
2216    // into `thread::Result::Err`. The `.unwrap()` then re-panics on
2217    // the main thread, which is the key test-profile behavior: the
2218    // libtest / nextest harness installs a per-test panic hook that
2219    // catches the re-panic and reports it as a failed test with the
2220    // reader-thread's payload preserved. The alternative —
2221    // `.map_err(|_| anyhow!("..."))` — would erase the reader-
2222    // thread panic payload, surface a generic string through `?`,
2223    // and make the test pass look like "drain step returned Err"
2224    // when the true failure was a panic inside `drain_capped` (an
2225    // indexing-out-of-bounds on a malformed stream, say). The
2226    // panic=abort caller contract holds in release (whole-process
2227    // abort); debug/test callers get a loud re-panic with the
2228    // original panic payload visible. Either way no `Err` reaches
2229    // the `?` below.
2230    let (stdout, _stdout_truncated) = match stdout_handle {
2231        Some(h) => h.join().unwrap().with_context(|| "read child stdout")?,
2232        None => (String::new(), false),
2233    };
2234    let (stderr, _stderr_truncated) = match stderr_handle {
2235        Some(h) => h.join().unwrap().with_context(|| "read child stderr")?,
2236        None => (String::new(), false),
2237    };
2238    Ok(SpawnOutput {
2239        stdout,
2240        stderr,
2241        exit_code: status.code().unwrap_or(-1),
2242    })
2243}
2244
2245/// Read `src` into a `String` with `MAX_CAPTURED_STREAM_BYTES` cap.
2246/// Returns `(buf, truncated)`. Emits a paired `eprintln!` +
2247/// `tracing::warn!` notice with the stream label (e.g. "stdout" /
2248/// "stderr") and cap byte count when the cap is hit.
2249///
2250/// Truncation is performed at the byte level on a `Vec<u8>` so a
2251/// split multi-byte UTF-8 char at the cap boundary cannot panic.
2252/// The final `String::from_utf8_lossy` replaces any invalid UTF-8
2253/// bytes with U+FFFD — including the partial-char split that byte
2254/// truncation can introduce. Non-truncated output preserves the
2255/// original bytes verbatim when it is already valid UTF-8; the
2256/// only behavioral delta vs the pre-cap `read_to_string` path is
2257/// that invalid UTF-8 in the child's full output now produces
2258/// replacement chars instead of an `io::ErrorKind::InvalidData`
2259/// upstream error. That trade is deliberate: past the cap there is
2260/// no way to report "invalid UTF-8" meaningfully since the tail is
2261/// gone, and making the pre-cap path lossy keeps semantics uniform.
2262fn drain_capped(src: impl std::io::Read, label: &'static str) -> std::io::Result<(String, bool)> {
2263    use std::io::Read;
2264    // One extra byte probes whether the source had more to offer —
2265    // `Take` returns EOF at exactly the cap, indistinguishable from
2266    // a child that emitted exactly `cap` bytes. We cap our own buffer
2267    // at MAX + 1 and check the read count.
2268    let mut raw: Vec<u8> = Vec::new();
2269    let n = src
2270        .take(MAX_CAPTURED_STREAM_BYTES + 1)
2271        .read_to_end(&mut raw)?;
2272    let truncated = n as u64 > MAX_CAPTURED_STREAM_BYTES;
2273    if truncated {
2274        raw.truncate(MAX_CAPTURED_STREAM_BYTES as usize);
2275        // Dual-emit: stderr for nextest-direct test runs (no
2276        // tracing subscriber installed in the default test-support
2277        // dispatch path), tracing for cargo-ktstr-wrapped runs and
2278        // structured-log consumers. Same rationale as the prefetch
2279        // notices — a silent-truncation warn that only reaches the
2280        // no-op dispatcher fails the visibility goal of this check.
2281        eprintln!(
2282            "ktstr: payload {label} exceeded {MAX_CAPTURED_STREAM_BYTES} bytes; tail discarded"
2283        );
2284        tracing::warn!(
2285            stream = label,
2286            cap_bytes = MAX_CAPTURED_STREAM_BYTES,
2287            "payload {label} exceeded capture cap; tail discarded",
2288        );
2289    }
2290    Ok((String::from_utf8_lossy(&raw).into_owned(), truncated))
2291}
2292
2293#[cfg(test)]
2294mod tests {
2295    use super::*;
2296    use crate::cgroup::CgroupManager;
2297    use crate::test_support::{MetricStream, OutputFormat, Polarity, Scheduler};
2298    use crate::topology::TestTopology;
2299
2300    // Minimal Ctx builder fixture for tests — no VM boot.
2301    fn make_ctx<'a>(
2302        cgroups: &'a CgroupManager,
2303        topo: &'a TestTopology,
2304    ) -> crate::scenario::Ctx<'a> {
2305        crate::scenario::Ctx::builder(cgroups, topo).build()
2306    }
2307
2308    /// Closure-form helper that owns the CgroupManager + TestTopology
2309    /// pair under the closure's stack frame so a Ctx borrowed from
2310    /// them stays valid for the closure body. Collapses the 3-line
2311    /// `cgroups + topo + make_ctx` setup that every payload_run test
2312    /// repeats. Tests pick the `parent` cgroup path: tests that never
2313    /// resolve against a real FS pass `"/nonexistent"`; tests that
2314    /// assert `resolve_cgroup_path` output pass `"/sys/fs/cgroup/test-parent"`.
2315    fn with_ctx<R>(parent: &str, f: impl FnOnce(&crate::scenario::Ctx<'_>) -> R) -> R {
2316        let cgroups = CgroupManager::new(parent);
2317        let topo = TestTopology::synthetic(4, 1);
2318        let ctx = make_ctx(&cgroups, &topo);
2319        f(&ctx)
2320    }
2321
2322    #[cfg(unix)]
2323    fn parse_proc_stat_state_and_pgrp(
2324        stat: &[u8],
2325        pid: libc::pid_t,
2326    ) -> std::io::Result<(u8, libc::pid_t)> {
2327        let delimiter = stat
2328            .windows(2)
2329            .rposition(|window| window == b") ")
2330            .ok_or_else(|| {
2331                std::io::Error::new(
2332                    std::io::ErrorKind::InvalidData,
2333                    format!("/proc/{pid}/stat has no command terminator"),
2334                )
2335            })?;
2336        let suffix = std::str::from_utf8(&stat[delimiter + 2..]).map_err(|error| {
2337            std::io::Error::new(
2338                std::io::ErrorKind::InvalidData,
2339                format!("/proc/{pid}/stat is not UTF-8 after its command: {error}"),
2340            )
2341        })?;
2342        let mut fields = suffix.split_ascii_whitespace();
2343        let state = fields
2344            .next()
2345            .and_then(|field| field.as_bytes().first().copied())
2346            .ok_or_else(|| {
2347                std::io::Error::new(
2348                    std::io::ErrorKind::InvalidData,
2349                    format!("/proc/{pid}/stat has no process state"),
2350                )
2351            })?;
2352        let _ppid = fields.next().ok_or_else(|| {
2353            std::io::Error::new(
2354                std::io::ErrorKind::InvalidData,
2355                format!("/proc/{pid}/stat has no parent pid"),
2356            )
2357        })?;
2358        let pgrp = fields
2359            .next()
2360            .ok_or_else(|| {
2361                std::io::Error::new(
2362                    std::io::ErrorKind::InvalidData,
2363                    format!("/proc/{pid}/stat has no process group"),
2364                )
2365            })?
2366            .parse()
2367            .map_err(|error| {
2368                std::io::Error::new(
2369                    std::io::ErrorKind::InvalidData,
2370                    format!("/proc/{pid}/stat has an invalid process group: {error}"),
2371                )
2372            })?;
2373        Ok((state, pgrp))
2374    }
2375
2376    #[cfg(unix)]
2377    fn live_process_group_members(pgid: libc::pid_t) -> std::io::Result<Vec<(libc::pid_t, u8)>> {
2378        let mut live = Vec::new();
2379        for entry in std::fs::read_dir("/proc")? {
2380            let entry = entry?;
2381            let Some(pid) = entry
2382                .file_name()
2383                .to_str()
2384                .and_then(|name| name.parse::<libc::pid_t>().ok())
2385            else {
2386                continue;
2387            };
2388            let stat = match std::fs::read(entry.path().join("stat")) {
2389                Ok(stat) => stat,
2390                Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
2391                Err(error) => return Err(error),
2392            };
2393            let (state, member_pgid) = parse_proc_stat_state_and_pgrp(&stat, pid)?;
2394            if member_pgid == pgid && !matches!(state, b'Z' | b'X' | b'x') {
2395                live.push((pid, state));
2396            }
2397        }
2398        Ok(live)
2399    }
2400
2401    /// Wait until a process group has no live members.
2402    ///
2403    /// `killpg(pgid, 0)` continues succeeding while a killed descendant is a
2404    /// zombie owned by an outer CI subreaper. Such a process is conclusively
2405    /// dead, but this test process cannot call `wait(2)` on it. Inspecting the
2406    /// process state keeps the teardown assertion strict about live members
2407    /// without confusing supervisor-owned zombies for surviving workloads.
2408    #[cfg(unix)]
2409    fn wait_for_process_group_termination(
2410        pgid: libc::pid_t,
2411        timeout: std::time::Duration,
2412        context: &str,
2413    ) {
2414        let deadline = std::time::Instant::now() + timeout;
2415        loop {
2416            // SAFETY: signal zero is an existence/permission probe and does
2417            // not alter any member of the process group.
2418            let probe = unsafe { libc::killpg(pgid, 0) };
2419            if probe != 0 {
2420                let error = std::io::Error::last_os_error();
2421                assert_eq!(
2422                    error.raw_os_error(),
2423                    Some(libc::ESRCH),
2424                    "unexpected errno probing process group {pgid} after {context}: {error}",
2425                );
2426                return;
2427            }
2428
2429            let live = live_process_group_members(pgid)
2430                .unwrap_or_else(|error| panic!("inspect process group {pgid}: {error}"));
2431            if live.is_empty() {
2432                return;
2433            }
2434            if std::time::Instant::now() >= deadline {
2435                panic!("process group {pgid} still has live members after {context}: {live:?}",);
2436            }
2437            std::thread::sleep(std::time::Duration::from_millis(20));
2438        }
2439    }
2440
2441    #[cfg(unix)]
2442    #[test]
2443    fn proc_stat_parser_handles_spaces_and_parentheses_in_comm() {
2444        let stat = b"37 (worker ) with spaces) S 11 29 29 0 -1";
2445        assert_eq!(
2446            parse_proc_stat_state_and_pgrp(stat, 37).expect("parse synthetic stat"),
2447            (b'S', 29),
2448        );
2449    }
2450
2451    const FIO_BINARY: Payload = Payload {
2452        name: "fio",
2453        kind: PayloadKind::Binary("fio"),
2454        output: OutputFormat::Json,
2455        default_args: &["--output-format=json"],
2456        default_checks: &[],
2457        metrics: &[],
2458        include_files: &[],
2459        uses_parent_pgrp: false,
2460        known_flags: None,
2461    };
2462
2463    const EEVDF_SCHED_PAYLOAD: Payload = Payload {
2464        name: "eevdf",
2465        kind: PayloadKind::Scheduler(&Scheduler::EEVDF),
2466        output: OutputFormat::ExitCode,
2467        default_args: &[],
2468        default_checks: &[],
2469        metrics: &[],
2470        include_files: &[],
2471        uses_parent_pgrp: false,
2472        known_flags: None,
2473    };
2474
2475    #[test]
2476    fn builder_inherits_default_args() {
2477        with_ctx("/nonexistent", |ctx| {
2478            let run = PayloadRun::new(ctx, &FIO_BINARY);
2479            assert_eq!(run.args, vec!["--output-format=json"]);
2480        });
2481    }
2482
2483    #[test]
2484    fn arg_appends() {
2485        with_ctx("/nonexistent", |ctx| {
2486            let run = PayloadRun::new(ctx, &FIO_BINARY)
2487                .arg("--runtime=30")
2488                .arg("job.fio");
2489            assert_eq!(
2490                run.args,
2491                vec!["--output-format=json", "--runtime=30", "job.fio"]
2492            );
2493        });
2494    }
2495
2496    #[test]
2497    fn clear_args_wipes_defaults() {
2498        with_ctx("/nonexistent", |ctx| {
2499            let run = PayloadRun::new(ctx, &FIO_BINARY)
2500                .clear_args()
2501                .arg("--custom");
2502            assert_eq!(run.args, vec!["--custom"]);
2503        });
2504    }
2505
2506    #[test]
2507    fn args_method_bulk_appends() {
2508        with_ctx("/nonexistent", |ctx| {
2509            let run = PayloadRun::new(ctx, &FIO_BINARY).args(["--a", "--b", "--c"]);
2510            assert_eq!(run.args, vec!["--output-format=json", "--a", "--b", "--c"]);
2511        });
2512    }
2513
2514    #[test]
2515    fn check_and_clear_checks() {
2516        with_ctx("/nonexistent", |ctx| {
2517            let run = PayloadRun::new(ctx, &FIO_BINARY)
2518                .check(MetricCheck::min("iops", 1000.0))
2519                .check(MetricCheck::max("latency", 500.0));
2520            assert_eq!(run.checks.len(), 2);
2521            let cleared = PayloadRun::new(ctx, &FIO_BINARY)
2522                .clear_checks()
2523                .check(MetricCheck::exit_code_eq(0));
2524            assert_eq!(cleared.checks.len(), 1);
2525        });
2526    }
2527
2528    #[test]
2529    fn in_cgroup_stores_name() {
2530        with_ctx("/nonexistent", |ctx| {
2531            let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup("fio_cg");
2532            assert_eq!(run.cgroup.as_deref(), Some("fio_cg"));
2533        });
2534    }
2535
2536    #[test]
2537    fn resolve_cgroup_path_strips_leading_slash_and_joins() {
2538        with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2539            // Leading "/" tolerated, joined under parent.
2540            let resolved = resolve_cgroup_path(ctx, Some("/workload"), "test::strips")
2541                .expect("valid cgroup name")
2542                .expect("Some(path)");
2543            assert_eq!(
2544                resolved,
2545                std::path::PathBuf::from("/sys/fs/cgroup/test-parent/workload")
2546            );
2547            // Same name without leading slash produces the same path.
2548            let plain = resolve_cgroup_path(ctx, Some("workload"), "test::strips")
2549                .expect("valid")
2550                .expect("Some");
2551            assert_eq!(resolved, plain);
2552        });
2553    }
2554
2555    #[test]
2556    fn resolve_cgroup_path_rejects_parent_dir() {
2557        with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2558            let err = resolve_cgroup_path(ctx, Some("../escape"), "PayloadRun::run")
2559                .expect_err("'..' must be rejected");
2560            let rendered = format!("{err:#}");
2561            assert!(rendered.contains(".."), "err: {rendered}");
2562            assert!(
2563                rendered.contains("PayloadRun::run"),
2564                "op label must appear in error: {rendered}",
2565            );
2566        });
2567    }
2568
2569    #[test]
2570    fn resolve_cgroup_path_rejects_nul_byte() {
2571        with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2572            let err = resolve_cgroup_path(ctx, Some("bad\0name"), "PayloadRun::spawn")
2573                .expect_err("NUL must be rejected");
2574            let rendered = format!("{err:#}");
2575            assert!(rendered.contains("NUL"), "err: {rendered}");
2576            assert!(
2577                rendered.contains("PayloadRun::spawn"),
2578                "op label must appear in error: {rendered}",
2579            );
2580        });
2581    }
2582
2583    #[test]
2584    fn resolve_cgroup_path_rejects_empty_after_strip() {
2585        with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2586            // "/" strips to empty — reject so we don't silently target
2587            // the parent cgroup itself.
2588            let err = resolve_cgroup_path(ctx, Some("/"), "PayloadRun::run")
2589                .expect_err("slash-only must be rejected");
2590            let rendered = format!("{err:#}");
2591            assert!(rendered.contains("empty"), "err: {rendered}");
2592            assert!(
2593                rendered.contains("PayloadRun::run"),
2594                "op label must appear in error: {rendered}",
2595            );
2596            let err = resolve_cgroup_path(ctx, Some(""), "PayloadRun::run")
2597                .expect_err("empty must be rejected");
2598            let rendered = format!("{err:#}");
2599            assert!(rendered.contains("empty"), "err: {rendered}");
2600            assert!(
2601                rendered.contains("PayloadRun::run"),
2602                "op label must appear in error: {rendered}",
2603            );
2604        });
2605    }
2606
2607    #[test]
2608    fn resolve_cgroup_path_none_passes_through() {
2609        with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2610            assert!(
2611                resolve_cgroup_path(ctx, None, "test::none")
2612                    .unwrap()
2613                    .is_none()
2614            );
2615        });
2616    }
2617
2618    /// Differential pin: the `op` label must flow through to the
2619    /// rendered error verbatim, distinct per caller. Catches the
2620    /// regression where the parameter is accepted but ignored
2621    /// (e.g. a refactor that hardcodes one label in the
2622    /// `anyhow!` message). Without this, per-caller assertions
2623    /// could pass against an implementation that drops the arg.
2624    #[test]
2625    fn resolve_cgroup_path_op_label_differs_per_caller() {
2626        with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2627            let err_a = format!(
2628                "{:#}",
2629                resolve_cgroup_path(ctx, Some("../bad"), "caller-a")
2630                    .expect_err("'..' must be rejected"),
2631            );
2632            let err_b = format!(
2633                "{:#}",
2634                resolve_cgroup_path(ctx, Some("../bad"), "caller-b")
2635                    .expect_err("'..' must be rejected"),
2636            );
2637            assert!(err_a.contains("caller-a"), "err_a: {err_a}");
2638            assert!(
2639                !err_a.contains("caller-b"),
2640                "err_a leaked caller-b: {err_a}"
2641            );
2642            assert!(err_b.contains("caller-b"), "err_b: {err_b}");
2643            assert!(
2644                !err_b.contains("caller-a"),
2645                "err_b leaked caller-a: {err_b}"
2646            );
2647        });
2648    }
2649
2650    /// Production-caller pin: the public `.run()` entry point must
2651    /// actually pass `"PayloadRun::run"` (and not, e.g.,
2652    /// `"PayloadRun::spawn"` via a copy-paste typo) when calling
2653    /// resolve_cgroup_path. The helper-level differential test above
2654    /// only proves the parameter isn't dropped — this test exercises
2655    /// the production call site inside `PayloadRun::run()` end-to-end.
2656    #[test]
2657    fn payload_run_run_threads_canonical_op_label() {
2658        with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2659            let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup("../escape");
2660            let err = run.run().unwrap_err();
2661            let rendered = format!("{err:#}");
2662            assert!(rendered.contains(".."), "err: {rendered}");
2663            assert!(
2664                rendered.contains("PayloadRun::run"),
2665                "production run() must pass PayloadRun::run as op label: {rendered}",
2666            );
2667        });
2668    }
2669
2670    /// Sibling of `payload_run_run_threads_canonical_op_label` for
2671    /// the `PayloadRun::spawn()` entry point. Uses a NUL-byte
2672    /// cgroup name (different validation branch from the run()
2673    /// test's `..`) to guard against a hypothetical refactor that
2674    /// hardcodes one op label across all anyhow! sites in
2675    /// resolve_cgroup_path.
2676    #[test]
2677    fn payload_run_spawn_threads_canonical_op_label() {
2678        with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2679            let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup("bad\0name");
2680            let err = run.spawn().unwrap_err();
2681            let rendered = format!("{err:#}");
2682            assert!(rendered.contains("NUL"), "err: {rendered}");
2683            assert!(
2684                rendered.contains("PayloadRun::spawn"),
2685                "production spawn() must pass PayloadRun::spawn as op label: {rendered}",
2686            );
2687        });
2688    }
2689
2690    #[test]
2691    fn run_rejects_scheduler_kind() {
2692        with_ctx("/nonexistent", |ctx| {
2693            let run = PayloadRun::new(ctx, &EEVDF_SCHED_PAYLOAD);
2694            let err = run.run().unwrap_err();
2695            assert!(
2696                format!("{err:#}").contains("scheduler-kind"),
2697                "err: {err:#}"
2698            );
2699        });
2700    }
2701
2702    #[test]
2703    fn evaluate_checks_passes_when_no_checks() {
2704        let pm = PayloadMetrics {
2705            payload_index: 0,
2706            metrics: vec![],
2707            exit_code: 0,
2708        };
2709        let r = evaluate_checks(&[], &pm, "");
2710        assert!(r.is_pass());
2711    }
2712
2713    #[test]
2714    fn evaluate_checks_exit_code_mismatch_fails_fast() {
2715        let pm = PayloadMetrics {
2716            payload_index: 0,
2717            metrics: vec![],
2718            exit_code: 42,
2719        };
2720        let checks = [
2721            MetricCheck::exit_code_eq(0),
2722            MetricCheck::min("iops", 100.0),
2723        ];
2724        let r = evaluate_checks(&checks, &pm, "");
2725        assert!(r.is_fail());
2726        // exit-code failure short-circuits — only one detail, not
2727        // a "missing metric" detail from the min check.
2728        assert_eq!(r.outcomes.len(), 1);
2729        assert!(
2730            r.failure_details()
2731                .next()
2732                .unwrap()
2733                .message
2734                .contains("exited with code 42"),
2735            "details: {:?}",
2736            r.outcomes
2737        );
2738    }
2739
2740    #[test]
2741    fn evaluate_checks_exit_code_mismatch_surfaces_stderr() {
2742        let pm = PayloadMetrics {
2743            payload_index: 0,
2744            metrics: vec![],
2745            exit_code: 1,
2746        };
2747        let r = evaluate_checks(
2748            &[MetricCheck::exit_code_eq(0)],
2749            &pm,
2750            "fatal: config missing\n",
2751        );
2752        assert!(r.is_fail());
2753        assert!(
2754            r.failure_details()
2755                .next()
2756                .unwrap()
2757                .message
2758                .contains("fatal: config missing"),
2759            "stderr tail must appear in detail: {:?}",
2760            r.outcomes,
2761        );
2762        assert!(
2763            r.failure_details()
2764                .next()
2765                .unwrap()
2766                .message
2767                .contains("stderr:"),
2768            "detail must label the stderr block: {:?}",
2769            r.outcomes,
2770        );
2771    }
2772
2773    #[test]
2774    fn evaluate_checks_exit_code_mismatch_without_stderr_stays_terse() {
2775        let pm = PayloadMetrics {
2776            payload_index: 0,
2777            metrics: vec![],
2778            exit_code: 1,
2779        };
2780        let r = evaluate_checks(&[MetricCheck::exit_code_eq(0)], &pm, "");
2781        assert!(r.is_fail());
2782        // Empty stderr → no "stderr:" prefix in the detail.
2783        assert!(
2784            !r.failure_details()
2785                .next()
2786                .unwrap()
2787                .message
2788                .contains("stderr:"),
2789            "empty stderr must not produce a stderr: block: {:?}",
2790            r.outcomes,
2791        );
2792    }
2793
2794    /// Signal-terminated payloads report `exit_code = -1` because
2795    /// `std::process::ExitStatus::code()` returns `None` on
2796    /// signal death and the spawn layer maps that to `-1` (see
2797    /// `spawn_and_wait`). A user who expects the signal-death
2798    /// case can assert `MetricCheck::exit_code_eq(-1)`, and the pre-pass
2799    /// comparison must pass under exact `i32` equality.
2800    #[test]
2801    fn evaluate_checks_exit_code_eq_negative_one_matches_signal_death() {
2802        let pm = PayloadMetrics {
2803            payload_index: 0,
2804            metrics: vec![],
2805            exit_code: -1,
2806        };
2807        let r = evaluate_checks(&[MetricCheck::exit_code_eq(-1)], &pm, "");
2808        assert!(
2809            r.is_pass(),
2810            "exit_code_eq(-1) must pass when exit_code == -1: {:?}",
2811            r.outcomes,
2812        );
2813    }
2814
2815    /// Symmetric negative case: `MetricCheck::exit_code_eq(-1)` against a
2816    /// CLEAN exit (`exit_code == 0`) must fail and surface the
2817    /// mismatch with both integers printed so the user sees what
2818    /// they asked for vs what happened.
2819    #[test]
2820    fn evaluate_checks_exit_code_eq_negative_one_fails_on_clean_exit() {
2821        let pm = PayloadMetrics {
2822            payload_index: 0,
2823            metrics: vec![],
2824            exit_code: 0,
2825        };
2826        let r = evaluate_checks(&[MetricCheck::exit_code_eq(-1)], &pm, "");
2827        assert!(r.is_fail());
2828        let msg = &*r.failure_details().next().unwrap().message;
2829        assert!(
2830            msg.contains("exited with code 0"),
2831            "mismatch detail must cite the actual exit code, got: {msg}"
2832        );
2833        assert!(
2834            msg.contains("-1"),
2835            "mismatch detail must cite the expected exit code, got: {msg}"
2836        );
2837    }
2838
2839    /// Reversed bounds (`lo > hi`) cannot reach the evaluator —
2840    /// `MetricCheck::range` panics at construction (see
2841    /// `check_range_reversed_bounds_panics_at_construction` in
2842    /// `test_support::payload`). Pin the constructor-side panic
2843    /// here so a future relaxation that lets reversed ranges flow
2844    /// into the evaluator (and silently fail every metric) trips
2845    /// this guard instead of slipping past CI.
2846    #[test]
2847    #[should_panic(expected = "lo must be <= hi")]
2848    fn evaluate_checks_range_reversed_bounds_panics_at_construction() {
2849        let _ = MetricCheck::range("iops", 100.0, 50.0);
2850    }
2851
2852    #[test]
2853    fn stderr_tail_truncates_long_input() {
2854        // Build >STDERR_TAIL_BYTES of ASCII so char-boundary logic
2855        // is a no-op and the tail size is deterministic.
2856        let long: String = "A".repeat(STDERR_TAIL_BYTES + 500);
2857        let tail = stderr_tail(&long, STDERR_TAIL_BYTES);
2858        assert!(tail.starts_with("..."));
2859        // Leading "..." + exactly STDERR_TAIL_BYTES of suffix.
2860        assert_eq!(tail.len(), STDERR_TAIL_BYTES + 3);
2861    }
2862
2863    #[test]
2864    fn stderr_tail_preserves_short_input() {
2865        let tail = stderr_tail("short error", STDERR_TAIL_BYTES);
2866        assert_eq!(tail, "short error");
2867    }
2868
2869    /// When `s.len() - max_bytes` lands inside a multi-byte UTF-8
2870    /// code unit, `stderr_tail` snaps the start index forward to the
2871    /// next char boundary so the slice operation never panics. This
2872    /// test uses a 2-byte UTF-8 character ("é") placed at the exact
2873    /// boundary so a naive `&s[start..]` would slice mid-codepoint.
2874    #[test]
2875    fn stderr_tail_snaps_forward_across_multibyte_char_boundary() {
2876        // "A"*10 + "é" + "B"*10 → 22 bytes total, len 22, "é" = 2 bytes.
2877        // With max_bytes = 11, start = 22 - 11 = 11. The byte at 11 is
2878        // the second byte of "é" (non-boundary). The snap-forward
2879        // advances start to 12, yielding the trailing "B"*10 + preamble.
2880        let mut s = String::from("A").repeat(10);
2881        s.push('é');
2882        s.push_str(&"B".repeat(10));
2883        let tail = stderr_tail(&s, 11);
2884        assert!(tail.starts_with("..."));
2885        // The multi-byte char must have been skipped (advanced off its
2886        // interior), so the tail begins with ASCII "B"s.
2887        assert!(
2888            tail[3..].starts_with('B'),
2889            "expected snap-forward past 'é', got: {tail:?}"
2890        );
2891    }
2892
2893    /// When the whole multi-byte character sits at the snap-forward
2894    /// boundary (start lands exactly on its first byte), the
2895    /// character is preserved intact — no off-by-one that drops its
2896    /// first byte.
2897    #[test]
2898    fn stderr_tail_preserves_multibyte_char_at_exact_boundary() {
2899        // Build a string so the multi-byte char starts exactly at the
2900        // snap-forward position. ASCII x10 + "é" (2B) + ASCII x10
2901        // = 22B. max_bytes = 12 → start = 22-12 = 10, which IS "é"'s
2902        // first byte (a boundary). No snap happens; "é" is included.
2903        let mut s = String::from("A").repeat(10);
2904        s.push('é');
2905        s.push_str(&"B".repeat(10));
2906        let tail = stderr_tail(&s, 12);
2907        assert!(tail.starts_with("..."));
2908        assert!(
2909            tail.contains('é'),
2910            "boundary-aligned multibyte char must survive the tail, got: {tail:?}"
2911        );
2912    }
2913
2914    /// For every `max_bytes` offset across a string with an interior
2915    /// multi-byte char, `stderr_tail`'s output is a faithful suffix of
2916    /// the input — not just valid UTF-8 (which `String` guarantees for
2917    /// free). The body after any leading `...` marker must be a suffix
2918    /// of `s`, and the truncation must never lengthen the content.
2919    /// Pins the slice CONTENT across every byte offset, catching a
2920    /// snap-direction or off-by-one regression that the prior
2921    /// discard-the-result loop could not see.
2922    #[test]
2923    fn stderr_tail_output_is_suffix_of_input_at_every_offset() {
2924        // Chinese "好" = 3 bytes (E5 A5 BD); pin it mid-string.
2925        let s = "xxxxxxxxxx好yyyyyyyyyy"; // 10 + 3 + 10 = 23 bytes
2926        for max in 1..=s.len() {
2927            let tail = stderr_tail(s, max);
2928            if s.len() <= max {
2929                // No truncation: returns the input verbatim, no marker.
2930                assert_eq!(tail, s, "max={max}: short input must round-trip");
2931                assert!(
2932                    !tail.starts_with("..."),
2933                    "max={max}: no marker when untruncated"
2934                );
2935            } else {
2936                // Truncated: leading "..." marker, then a suffix of s.
2937                let body = tail.strip_prefix("...").unwrap_or_else(|| {
2938                    panic!("max={max}: truncated output must carry the marker, got {tail:?}")
2939                });
2940                assert!(
2941                    s.ends_with(body),
2942                    "max={max}: body {body:?} must be a suffix of the input {s:?}",
2943                );
2944                // Snap-forward only ever drops bytes from the front, so
2945                // the retained suffix is at most `max` bytes and never
2946                // longer than the input.
2947                assert!(
2948                    body.len() <= max,
2949                    "max={max}: retained suffix {} bytes exceeds the {max}-byte budget",
2950                    body.len(),
2951                );
2952                // The boundary snap must keep the suffix a valid char
2953                // boundary of s (no mid-codepoint split) — equivalent
2954                // to: stripping `body` off the end of s leaves a valid
2955                // str whose remainder + body reconstructs s exactly.
2956                let head_len = s.len() - body.len();
2957                assert!(
2958                    s.is_char_boundary(head_len),
2959                    "max={max}: suffix start {head_len} must be a char boundary of {s:?}",
2960                );
2961            }
2962        }
2963    }
2964
2965    /// Production-scale counterpart to the boundary tests above. The
2966    /// existing small-string cases use ~20 bytes, well below the
2967    /// production [`STDERR_TAIL_BYTES`] threshold of 1024. This test
2968    /// lands a multi-byte character's interior byte on the truncation
2969    /// offset of a >1 KiB string, matching the actual shape of an
2970    /// overflowing stderr from a real payload. The snap-forward must
2971    /// advance past the interior byte so `stderr_tail` does not panic
2972    /// on mid-codepoint slicing.
2973    #[test]
2974    fn stderr_tail_snaps_forward_at_production_threshold() {
2975        // Layout: "A"*100 + "é" (2B) + "B"*1023 = 1125 bytes.
2976        // start = 1125 - 1024 = 101 — the interior byte of "é"
2977        // (whose boundary bytes are at 100 and 102). The snap-forward
2978        // advances start to 102, so the tail begins with the "B"
2979        // suffix rather than a corrupt split "é".
2980        let mut s = "A".repeat(100);
2981        s.push('é');
2982        s.push_str(&"B".repeat(1023));
2983        assert!(
2984            s.len() > STDERR_TAIL_BYTES,
2985            "fixture must exceed STDERR_TAIL_BYTES to exercise the truncation path",
2986        );
2987        let tail = stderr_tail(&s, STDERR_TAIL_BYTES);
2988        assert!(tail.starts_with("..."));
2989        assert!(
2990            tail[3..].starts_with('B'),
2991            "expected snap-forward past 'é' interior byte at >1 KiB, got prefix: {:?}",
2992            &tail[..20.min(tail.len())],
2993        );
2994    }
2995
2996    /// Production-scale complement: when the truncation offset lands
2997    /// exactly on a multi-byte character's first byte (a boundary),
2998    /// the character survives — no off-by-one that would drop it.
2999    /// Covers the is_char_boundary-true branch of the snap-forward
3000    /// loop at the real [`STDERR_TAIL_BYTES`] size.
3001    #[test]
3002    fn stderr_tail_preserves_multibyte_at_production_boundary() {
3003        // Layout: "A"*100 + "é" (2B) + "B"*1022 = 1124 bytes.
3004        // start = 1124 - 1024 = 100 — the first byte of "é" (which
3005        // IS a char boundary). No snap runs; "é" is included whole.
3006        let mut s = "A".repeat(100);
3007        s.push('é');
3008        s.push_str(&"B".repeat(1022));
3009        assert!(
3010            s.len() > STDERR_TAIL_BYTES,
3011            "fixture must exceed STDERR_TAIL_BYTES to exercise the truncation path",
3012        );
3013        let tail = stderr_tail(&s, STDERR_TAIL_BYTES);
3014        assert!(tail.starts_with("..."));
3015        assert!(
3016            tail.contains('é'),
3017            "boundary-aligned 'é' at the >1 KiB truncation offset must survive, got prefix: {:?}",
3018            &tail[..40.min(tail.len())],
3019        );
3020    }
3021
3022    #[test]
3023    fn evaluate_checks_missing_metric_fails_loudly() {
3024        let pm = PayloadMetrics {
3025            payload_index: 0,
3026            metrics: vec![],
3027            exit_code: 0,
3028        };
3029        let checks = [MetricCheck::min("iops", 100.0)];
3030        let r = evaluate_checks(&checks, &pm, "");
3031        assert!(r.is_fail());
3032        assert!(
3033            r.failure_details()
3034                .next()
3035                .unwrap()
3036                .message
3037                .contains("not found"),
3038            "details: {:?}",
3039            r.outcomes
3040        );
3041    }
3042
3043    #[test]
3044    fn evaluate_checks_min_below_threshold_fails() {
3045        let pm = PayloadMetrics {
3046            payload_index: 0,
3047            metrics: vec![Metric {
3048                name: "iops".to_string(),
3049                value: 50.0,
3050                polarity: Polarity::HigherBetter,
3051                unit: String::new(),
3052                stream: MetricStream::Stdout,
3053            }],
3054            exit_code: 0,
3055        };
3056        let r = evaluate_checks(&[MetricCheck::min("iops", 100.0)], &pm, "");
3057        assert!(r.is_fail());
3058        assert!(
3059            r.failure_details()
3060                .next()
3061                .unwrap()
3062                .message
3063                .contains("below minimum")
3064        );
3065    }
3066
3067    #[test]
3068    fn evaluate_checks_max_above_threshold_fails() {
3069        let pm = PayloadMetrics {
3070            payload_index: 0,
3071            metrics: vec![Metric {
3072                name: "lat".to_string(),
3073                value: 1000.0,
3074                polarity: Polarity::LowerBetter,
3075                unit: String::new(),
3076                stream: MetricStream::Stdout,
3077            }],
3078            exit_code: 0,
3079        };
3080        let r = evaluate_checks(&[MetricCheck::max("lat", 500.0)], &pm, "");
3081        assert!(r.is_fail());
3082        assert!(
3083            r.failure_details()
3084                .next()
3085                .unwrap()
3086                .message
3087                .contains("exceeds maximum")
3088        );
3089    }
3090
3091    #[test]
3092    fn evaluate_checks_range_out_of_bounds_fails() {
3093        let pm = PayloadMetrics {
3094            payload_index: 0,
3095            metrics: vec![Metric {
3096                name: "cpu".to_string(),
3097                value: 150.0,
3098                polarity: Polarity::Unknown,
3099                unit: String::new(),
3100                stream: MetricStream::Stdout,
3101            }],
3102            exit_code: 0,
3103        };
3104        let r = evaluate_checks(&[MetricCheck::range("cpu", 0.0, 100.0)], &pm, "");
3105        assert!(r.is_fail());
3106        assert!(
3107            r.failure_details()
3108                .next()
3109                .unwrap()
3110                .message
3111                .contains("outside")
3112        );
3113    }
3114
3115    /// IEEE 754 makes every comparison against NaN evaluate to
3116    /// false, so a naive `actual < min` would silently pass a
3117    /// `Min` check on a NaN-valued metric — exactly the case
3118    /// operators most need to flag, since NaN almost always means
3119    /// the metric extraction itself is broken (divide-by-zero,
3120    /// unparsed token, typed-measurement error). The fix routes
3121    /// NaN through `nan_metric` BEFORE the bound comparison, so
3122    /// the failure reads "metric '...' value is NaN" rather than
3123    /// silently green-lighting an unmeasurable value.
3124    #[test]
3125    fn evaluate_checks_min_nan_fails_with_nan_message() {
3126        let pm = PayloadMetrics {
3127            payload_index: 0,
3128            metrics: vec![Metric {
3129                name: "iops".to_string(),
3130                value: f64::NAN,
3131                polarity: Polarity::HigherBetter,
3132                unit: String::new(),
3133                stream: MetricStream::Stdout,
3134            }],
3135            exit_code: 0,
3136        };
3137        let r = evaluate_checks(&[MetricCheck::min("iops", 100.0)], &pm, "");
3138        assert!(!r.is_pass(), "NaN value must fail Min check");
3139        assert!(
3140            r.failure_details()
3141                .next()
3142                .unwrap()
3143                .message
3144                .contains("value is NaN"),
3145            "NaN failure must surface the dedicated message: {:?}",
3146            r.outcomes
3147        );
3148    }
3149
3150    /// Sibling of [`evaluate_checks_min_nan_fails_with_nan_message`]
3151    /// for the upper-bound path — `actual > max` is also false for
3152    /// NaN.
3153    #[test]
3154    fn evaluate_checks_max_nan_fails_with_nan_message() {
3155        let pm = PayloadMetrics {
3156            payload_index: 0,
3157            metrics: vec![Metric {
3158                name: "lat".to_string(),
3159                value: f64::NAN,
3160                polarity: Polarity::LowerBetter,
3161                unit: String::new(),
3162                stream: MetricStream::Stdout,
3163            }],
3164            exit_code: 0,
3165        };
3166        let r = evaluate_checks(&[MetricCheck::max("lat", 500.0)], &pm, "");
3167        assert!(!r.is_pass(), "NaN value must fail Max check");
3168        assert!(
3169            r.failure_details()
3170                .next()
3171                .unwrap()
3172                .message
3173                .contains("value is NaN"),
3174            "NaN failure must surface the dedicated message: {:?}",
3175            r.outcomes
3176        );
3177    }
3178
3179    /// Range gate sees NaN through both `actual < lo` and
3180    /// `actual > hi` — both false, so the legacy code accepted
3181    /// NaN as in-range. The fix routes NaN through `nan_metric`
3182    /// before the range comparison.
3183    #[test]
3184    fn evaluate_checks_range_nan_fails_with_nan_message() {
3185        let pm = PayloadMetrics {
3186            payload_index: 0,
3187            metrics: vec![Metric {
3188                name: "cpu".to_string(),
3189                value: f64::NAN,
3190                polarity: Polarity::Unknown,
3191                unit: String::new(),
3192                stream: MetricStream::Stdout,
3193            }],
3194            exit_code: 0,
3195        };
3196        let r = evaluate_checks(&[MetricCheck::range("cpu", 0.0, 100.0)], &pm, "");
3197        assert!(!r.is_pass(), "NaN value must fail Range check");
3198        assert!(
3199            r.failure_details()
3200                .next()
3201                .unwrap()
3202                .message
3203                .contains("value is NaN"),
3204            "NaN failure must surface the dedicated message: {:?}",
3205            r.outcomes
3206        );
3207    }
3208
3209    #[test]
3210    fn evaluate_checks_exists_missing_fails() {
3211        let pm = PayloadMetrics {
3212            payload_index: 0,
3213            metrics: vec![],
3214            exit_code: 0,
3215        };
3216        let r = evaluate_checks(&[MetricCheck::exists("thing")], &pm, "");
3217        assert!(r.is_fail());
3218    }
3219
3220    #[test]
3221    fn evaluate_checks_all_pass_returns_pass() {
3222        let pm = PayloadMetrics {
3223            payload_index: 0,
3224            metrics: vec![Metric {
3225                name: "iops".to_string(),
3226                value: 5000.0,
3227                polarity: Polarity::HigherBetter,
3228                unit: String::new(),
3229                stream: MetricStream::Stdout,
3230            }],
3231            exit_code: 0,
3232        };
3233        let r = evaluate_checks(
3234            &[
3235                MetricCheck::exit_code_eq(0),
3236                MetricCheck::min("iops", 1000.0),
3237                MetricCheck::exists("iops"),
3238            ],
3239            &pm,
3240            "",
3241        );
3242        assert!(r.is_pass());
3243    }
3244
3245    /// Multiple checks on the same metric all fire — the evaluator
3246    /// does not dedup by metric name. Two `Min`s on the same path
3247    /// either both pass (value >= max threshold) or both fail
3248    /// (value < one of the thresholds, depending on which is more
3249    /// restrictive). This test uses a pair where the metric value
3250    /// (100) is below the second threshold (200) but above the
3251    /// first (50). The second failure must appear in the details
3252    /// list — the evaluator must not short-circuit after the first
3253    /// matching metric check.
3254    #[test]
3255    fn evaluate_checks_duplicate_min_on_same_metric_both_evaluated() {
3256        let pm = PayloadMetrics {
3257            payload_index: 0,
3258            metrics: vec![Metric {
3259                name: "iops".to_string(),
3260                value: 100.0,
3261                polarity: Polarity::HigherBetter,
3262                unit: String::new(),
3263                stream: MetricStream::Stdout,
3264            }],
3265            exit_code: 0,
3266        };
3267        let r = evaluate_checks(
3268            &[
3269                MetricCheck::min("iops", 50.0),
3270                MetricCheck::min("iops", 200.0),
3271            ],
3272            &pm,
3273            "",
3274        );
3275        assert!(!r.is_pass(), "second min must fail");
3276        assert_eq!(r.outcomes.len(), 1, "only the failing check emits a detail");
3277        // The passing check produces no detail; only the failing one
3278        // shows up. The message must reference the 200 threshold.
3279        assert!(
3280            r.failure_details()
3281                .next()
3282                .unwrap()
3283                .message
3284                .contains("below minimum 200"),
3285            "failing check must cite its threshold: {:?}",
3286            r.outcomes,
3287        );
3288    }
3289
3290    /// Two conflicting checks on the same metric (Min 100 and Max 50)
3291    /// produce TWO failures in the details list — not one collapsed
3292    /// failure. Pins the "each check evaluated independently"
3293    /// invariant so a future optimization doesn't accidentally merge
3294    /// / dedup.
3295    #[test]
3296    fn evaluate_checks_conflicting_checks_on_same_metric_both_report() {
3297        let pm = PayloadMetrics {
3298            payload_index: 0,
3299            metrics: vec![Metric {
3300                name: "iops".to_string(),
3301                value: 75.0,
3302                polarity: Polarity::HigherBetter,
3303                unit: String::new(),
3304                stream: MetricStream::Stdout,
3305            }],
3306            exit_code: 0,
3307        };
3308        let r = evaluate_checks(
3309            &[
3310                MetricCheck::min("iops", 100.0), // 75 < 100: fail
3311                MetricCheck::max("iops", 50.0),  // 75 > 50: fail
3312            ],
3313            &pm,
3314            "",
3315        );
3316        assert!(r.is_fail());
3317        assert_eq!(
3318            r.outcomes.len(),
3319            2,
3320            "both conflicting checks must each emit a detail: {:?}",
3321            r.outcomes,
3322        );
3323    }
3324
3325    /// `MetricCheck::Exists` with a zero-value metric passes. The check is
3326    /// presence-only — a metric of 0.0 is still present in the
3327    /// PayloadMetrics map and `pm.get(name).is_some()` returns true.
3328    /// A naive `pm.get(name).filter(|v| *v != 0.0)` would spuriously
3329    /// fail here; pin the "exists is sign-agnostic and zero-
3330    /// friendly" invariant.
3331    #[test]
3332    fn evaluate_checks_exists_passes_for_zero_value_metric() {
3333        let pm = PayloadMetrics {
3334            payload_index: 0,
3335            metrics: vec![Metric {
3336                name: "errors".to_string(),
3337                value: 0.0,
3338                polarity: Polarity::LowerBetter,
3339                unit: String::new(),
3340                stream: MetricStream::Stdout,
3341            }],
3342            exit_code: 0,
3343        };
3344        let r = evaluate_checks(&[MetricCheck::exists("errors")], &pm, "");
3345        assert!(
3346            r.is_pass(),
3347            "exists('errors') must pass when metric is 0.0: {:?}",
3348            r.outcomes,
3349        );
3350    }
3351
3352    /// Negative zero (`-0.0`) also counts as present for
3353    /// `MetricCheck::Exists`. Paranoid pin because f64 `-0.0` surprises
3354    /// some pattern-matching code (`0.0 == -0.0` but they differ
3355    /// under `f64::to_bits`).
3356    #[test]
3357    fn evaluate_checks_exists_passes_for_negative_zero() {
3358        let pm = PayloadMetrics {
3359            payload_index: 0,
3360            metrics: vec![Metric {
3361                name: "drift".to_string(),
3362                value: -0.0,
3363                polarity: Polarity::Unknown,
3364                unit: String::new(),
3365                stream: MetricStream::Stdout,
3366            }],
3367            exit_code: 0,
3368        };
3369        let r = evaluate_checks(&[MetricCheck::exists("drift")], &pm, "");
3370        assert!(r.is_pass());
3371    }
3372
3373    /// `PayloadRun`'s custom `Debug` impl renders the stable
3374    /// identity fields — payload name, args/checks lengths, and
3375    /// cgroup placement — without dumping the `Ctx` pointer. Pins
3376    /// the output shape so a future rename can't silently drop a
3377    /// field that debug-printing consumers rely on.
3378    #[test]
3379    fn payload_run_debug_renders_identity_fields() {
3380        with_ctx("/nonexistent", |ctx| {
3381            let run = PayloadRun::new(ctx, &TRUE_BIN)
3382                .arg("--foo")
3383                .arg("--bar")
3384                .check(MetricCheck::exit_code_eq(0))
3385                .in_cgroup("workers");
3386            let s = format!("{run:?}");
3387            assert!(s.contains("PayloadRun"), "prefix: {s}");
3388            assert!(s.contains("payload:"), "payload field: {s}");
3389            assert!(s.contains("true_bin"), "payload name: {s}");
3390            assert!(s.contains("args_len"), "args_len field: {s}");
3391            assert!(s.contains("checks_len"), "checks_len field: {s}");
3392            assert!(s.contains("cgroup:"), "cgroup field: {s}");
3393            // Values: 2 args added (on top of 0 default) + 1 check.
3394            assert!(s.contains("args_len: 2"), "computed args_len: {s}");
3395            assert!(s.contains("checks_len: 1"), "computed checks_len: {s}");
3396            // cgroup is Some("workers"); the debug form of Cow<str>
3397            // renders as "workers" inside Some(..).
3398            assert!(s.contains("workers"), "cgroup value: {s}");
3399            // Must NOT leak the Ctx pointer (no raw-address tokens).
3400            assert!(
3401                !s.contains("Ctx {"),
3402                "Ctx should not appear in PayloadRun Debug: {s}"
3403            );
3404        });
3405    }
3406
3407    /// Default `PayloadRun` (no args, no checks, no cgroup)
3408    /// renders sensible zeroes.
3409    #[test]
3410    fn payload_run_debug_renders_defaults() {
3411        with_ctx("/nonexistent", |ctx| {
3412            let run = PayloadRun::new(ctx, &TRUE_BIN);
3413            let s = format!("{run:?}");
3414            assert!(s.contains("args_len: 0"), "default args_len: {s}");
3415            assert!(s.contains("checks_len: 0"), "default checks_len: {s}");
3416            assert!(s.contains("cgroup: None"), "default cgroup: {s}");
3417        });
3418    }
3419
3420    #[test]
3421    fn resolve_polarities_applies_hints() {
3422        let mut metrics = vec![Metric {
3423            name: "iops".to_string(),
3424            value: 100.0,
3425            polarity: Polarity::Unknown,
3426            unit: String::new(),
3427            stream: MetricStream::Stdout,
3428        }];
3429        const HINTED: Payload = Payload {
3430            name: "p",
3431            kind: PayloadKind::Binary("p"),
3432            output: OutputFormat::Json,
3433            default_args: &[],
3434            default_checks: &[],
3435            metrics: &[crate::test_support::MetricHint {
3436                name: "iops",
3437                polarity: Polarity::HigherBetter,
3438                unit: "iops",
3439            }],
3440            include_files: &[],
3441            uses_parent_pgrp: false,
3442            known_flags: None,
3443        };
3444        resolve_polarities(&mut metrics, &HINTED);
3445        assert_eq!(metrics[0].polarity, Polarity::HigherBetter);
3446        assert_eq!(metrics[0].unit, "iops");
3447    }
3448
3449    // -- PayloadHandle + .spawn() tests --
3450
3451    const TRUE_BIN: Payload = Payload::binary("true_bin", "/bin/true");
3452    const FALSE_BIN: Payload = Payload::binary("false_bin", "/bin/false");
3453
3454    #[test]
3455    fn spawn_rejects_scheduler_kind() {
3456        with_ctx("/nonexistent", |ctx| {
3457            let run = PayloadRun::new(ctx, &EEVDF_SCHED_PAYLOAD);
3458            let err = run.spawn().unwrap_err();
3459            assert!(
3460                format!("{err:#}").contains("scheduler-kind"),
3461                "err: {err:#}"
3462            );
3463        });
3464    }
3465
3466    #[test]
3467    fn spawn_then_wait_returns_result_and_metrics() {
3468        with_ctx("/nonexistent", |ctx| {
3469            let handle = PayloadRun::new(ctx, &TRUE_BIN)
3470                .spawn()
3471                .expect("spawn /bin/true");
3472            let (result, metrics) = handle.wait().expect("wait");
3473            assert!(result.is_pass());
3474            assert_eq!(metrics.exit_code, 0);
3475        });
3476    }
3477
3478    #[test]
3479    fn spawn_then_kill_returns_collected_output() {
3480        with_ctx("/nonexistent", |ctx| {
3481            // /bin/sleep runs for a while; .kill() terminates it.
3482            const SLEEPER: Payload = Payload {
3483                name: "sleeper",
3484                kind: PayloadKind::Binary("/bin/sleep"),
3485                output: crate::test_support::OutputFormat::ExitCode,
3486                default_args: &["60"],
3487                default_checks: &[],
3488                metrics: &[],
3489                include_files: &[],
3490                uses_parent_pgrp: false,
3491                known_flags: None,
3492            };
3493            let handle = PayloadRun::new(ctx, &SLEEPER).spawn().expect("spawn sleep");
3494            let (_result, metrics) = handle.kill().expect("kill+collect");
3495            // Killed process produces a non-zero exit (SIGKILL -> None
3496            // status code, wait_and_capture maps to -1).
3497            assert_ne!(metrics.exit_code, 0);
3498        });
3499    }
3500
3501    #[test]
3502    fn spawn_try_wait_returns_none_while_running() {
3503        with_ctx("/nonexistent", |ctx| {
3504            const SLEEPER: Payload = Payload {
3505                name: "sleeper3",
3506                kind: PayloadKind::Binary("/bin/sleep"),
3507                output: crate::test_support::OutputFormat::ExitCode,
3508                default_args: &["60"],
3509                default_checks: &[],
3510                metrics: &[],
3511                include_files: &[],
3512                uses_parent_pgrp: false,
3513                known_flags: None,
3514            };
3515            let mut handle = PayloadRun::new(ctx, &SLEEPER).spawn().expect("spawn sleep");
3516            // Not yet exited.
3517            assert!(handle.try_wait().expect("try_wait").is_none());
3518            // Cleanup — kill so Drop warning doesn't fire.
3519            let _ = handle.kill();
3520        });
3521    }
3522
3523    #[test]
3524    fn spawn_try_wait_returns_some_after_exit() {
3525        with_ctx("/nonexistent", |ctx| {
3526            let mut handle = PayloadRun::new(ctx, &TRUE_BIN)
3527                .spawn()
3528                .expect("spawn /bin/true");
3529            // /bin/true exits quickly. Poll a few times.
3530            let mut result = None;
3531            for _ in 0..100 {
3532                if let Some(r) = handle.try_wait().expect("try_wait") {
3533                    result = Some(r);
3534                    break;
3535                }
3536                std::thread::sleep(std::time::Duration::from_millis(10));
3537            }
3538            let (r, metrics) = result.expect("try_wait eventually returns Some");
3539            assert!(r.is_pass());
3540            assert_eq!(metrics.exit_code, 0);
3541        });
3542    }
3543
3544    #[test]
3545    fn spawn_false_binary_produces_failing_exit_code() {
3546        with_ctx("/nonexistent", |ctx| {
3547            let handle = PayloadRun::new(ctx, &FALSE_BIN)
3548                .spawn()
3549                .expect("spawn /bin/false");
3550            let (_result, metrics) = handle.wait().expect("wait");
3551            assert_ne!(metrics.exit_code, 0);
3552        });
3553    }
3554
3555    #[test]
3556    fn resolve_polarities_leaves_unhinted_alone() {
3557        let mut metrics = vec![Metric {
3558            name: "no_hint".to_string(),
3559            value: 1.0,
3560            polarity: Polarity::Unknown,
3561            unit: String::new(),
3562            stream: MetricStream::Stdout,
3563        }];
3564        resolve_polarities(&mut metrics, &FIO_BINARY);
3565        assert_eq!(metrics[0].polarity, Polarity::Unknown);
3566        assert_eq!(metrics[0].unit, "");
3567    }
3568
3569    // -- Builder-composition + evaluator-coverage regression tests --
3570
3571    #[test]
3572    fn evaluate_checks_three_failing_checks_produce_three_details() {
3573        // Exit-code check passes (0 == 0), so pre-pass does not
3574        // short-circuit; all three metric checks fail and each must
3575        // contribute its own AssertDetail — regression guard
3576        // against detail dedup/overwrite bugs.
3577        let pm = PayloadMetrics {
3578            payload_index: 0,
3579            metrics: vec![
3580                Metric {
3581                    name: "iops".to_string(),
3582                    value: 10.0,
3583                    polarity: Polarity::HigherBetter,
3584                    unit: String::new(),
3585                    stream: MetricStream::Stdout,
3586                },
3587                Metric {
3588                    name: "lat".to_string(),
3589                    value: 900.0,
3590                    polarity: Polarity::LowerBetter,
3591                    unit: String::new(),
3592                    stream: MetricStream::Stdout,
3593                },
3594                Metric {
3595                    name: "cpu".to_string(),
3596                    value: 200.0,
3597                    polarity: Polarity::Unknown,
3598                    unit: String::new(),
3599                    stream: MetricStream::Stdout,
3600                },
3601            ],
3602            exit_code: 0,
3603        };
3604        let checks = [
3605            MetricCheck::exit_code_eq(0),
3606            MetricCheck::min("iops", 1000.0),
3607            MetricCheck::max("lat", 100.0),
3608            MetricCheck::range("cpu", 0.0, 100.0),
3609        ];
3610        let r = evaluate_checks(&checks, &pm, "");
3611        assert!(r.is_fail());
3612        assert_eq!(
3613            r.outcomes.len(),
3614            3,
3615            "expected one detail per failed metric check, got: {:?}",
3616            r.outcomes,
3617        );
3618        // Each check's message must surface — not an aggregate or
3619        // a deduped first-only line.
3620        assert!(r.failure_details().any(|d| d.message.contains("iops")));
3621        assert!(r.failure_details().any(|d| d.message.contains("lat")));
3622        assert!(r.failure_details().any(|d| d.message.contains("cpu")));
3623    }
3624
3625    #[test]
3626    fn arg_then_clear_args_then_arg_yields_only_the_final_arg() {
3627        // clear_args() wipes EVERYTHING — the default_args AND any
3628        // previously-appended .arg(...) — and subsequent .arg(...)
3629        // calls start from empty. Regression guard for the
3630        // "clear_args truncates, arg appends" contract.
3631        with_ctx("/nonexistent", |ctx| {
3632            let run = PayloadRun::new(ctx, &FIO_BINARY)
3633                .arg("--x")
3634                .clear_args()
3635                .arg("--y");
3636            assert_eq!(run.args, vec!["--y"]);
3637        });
3638    }
3639
3640    #[test]
3641    fn default_checks_are_inherited_by_new_builder() {
3642        // Payload.default_checks are the starting check list: they
3643        // MUST be present on a fresh PayloadRun before any runtime
3644        // .check() calls. `.check` appends on top, `.clear_checks`
3645        // wipes them.
3646        const CHECKED: Payload = Payload {
3647            name: "checked",
3648            kind: PayloadKind::Binary("checked"),
3649            output: OutputFormat::ExitCode,
3650            default_args: &[],
3651            default_checks: &[
3652                MetricCheck::exit_code_eq(0),
3653                MetricCheck::min("iops", 500.0),
3654            ],
3655            metrics: &[],
3656            include_files: &[],
3657            uses_parent_pgrp: false,
3658            known_flags: None,
3659        };
3660        with_ctx("/nonexistent", |ctx| {
3661            // Fresh builder inherits both default checks in order.
3662            let fresh = PayloadRun::new(ctx, &CHECKED);
3663            assert_eq!(fresh.checks.len(), 2);
3664            assert!(matches!(fresh.checks[0], MetricCheck::ExitCodeEq(0)));
3665            assert!(matches!(
3666                fresh.checks[1],
3667                MetricCheck::Min { value, .. } if value == 500.0,
3668            ));
3669
3670            // Appending preserves defaults and adds on top.
3671            let appended = PayloadRun::new(ctx, &CHECKED).check(MetricCheck::exists("latency"));
3672            assert_eq!(appended.checks.len(), 3);
3673
3674            // Clearing wipes defaults too.
3675            let cleared = PayloadRun::new(ctx, &CHECKED).clear_checks();
3676            assert!(cleared.checks.is_empty());
3677        });
3678    }
3679
3680    #[test]
3681    fn in_cgroup_accepts_static_str_zero_alloc() {
3682        // Static &'static str goes in as Cow::Borrowed; no heap
3683        // allocation happens for the common case of a const cgroup
3684        // name. Regression guard for the Cow<'static, str> API shape.
3685        with_ctx("/nonexistent", |ctx| {
3686            let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup("workload");
3687            match &run.cgroup {
3688                Some(Cow::Borrowed(s)) => assert_eq!(*s, "workload"),
3689                other => panic!("expected Cow::Borrowed for &'static str input, got {other:?}"),
3690            }
3691        });
3692    }
3693
3694    #[test]
3695    fn in_cgroup_accepts_owned_string() {
3696        // Owned String goes in as Cow::Owned; the builder must not
3697        // require the caller to convert themselves.
3698        with_ctx("/nonexistent", |ctx| {
3699            let name = String::from("dynamic");
3700            let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup(name);
3701            match &run.cgroup {
3702                Some(Cow::Owned(s)) => assert_eq!(s, "dynamic"),
3703                other => panic!("expected Cow::Owned for String input, got {other:?}"),
3704            }
3705        });
3706    }
3707
3708    /// Host-side decode of a guest-emitted [`crate::test_support::PayloadMetrics`] JSON
3709    /// body must round-trip exactly — the SHM transport only carries
3710    /// bytes, and a schema drift between emit-side (serde_json on a
3711    /// `PayloadMetrics`) and drain-side (serde_json::from_slice) would
3712    /// silently drop metrics from the sidecar.
3713    #[test]
3714    fn payload_metrics_shm_payload_json_round_trip() {
3715        let emit = PayloadMetrics {
3716            payload_index: 0,
3717            metrics: vec![
3718                Metric {
3719                    name: "jobs.0.read.iops".to_string(),
3720                    value: 12345.0,
3721                    polarity: Polarity::HigherBetter,
3722                    unit: "iops".to_string(),
3723                    stream: MetricStream::Stdout,
3724                },
3725                Metric {
3726                    name: "lat_ns".to_string(),
3727                    value: 500.0,
3728                    polarity: Polarity::LowerBetter,
3729                    unit: "ns".to_string(),
3730                    stream: MetricStream::Stdout,
3731                },
3732            ],
3733            exit_code: 0,
3734        };
3735        let bytes = serde_json::to_vec(&emit).expect("serialize PayloadMetrics");
3736        let decoded: PayloadMetrics =
3737            serde_json::from_slice(&bytes).expect("decode PayloadMetrics from JSON bytes");
3738        assert_eq!(decoded.exit_code, emit.exit_code);
3739        assert_eq!(decoded.metrics.len(), emit.metrics.len());
3740        for (a, b) in decoded.metrics.iter().zip(emit.metrics.iter()) {
3741            assert_eq!(a.name, b.name);
3742            assert_eq!(a.value, b.value);
3743            assert_eq!(a.polarity, b.polarity);
3744            assert_eq!(a.unit, b.unit);
3745        }
3746    }
3747
3748    /// Hinted metrics pick up polarity + unit from the payload's
3749    /// declared MetricHints regardless of declaration order. Also
3750    /// pins that resolve_polarities leaves unhinted metrics at
3751    /// Polarity::Unknown / empty unit — the non-over-applying
3752    /// invariant the prior linear scan had.
3753    #[test]
3754    fn resolve_polarities_applies_hints_by_name_lookup() {
3755        use crate::test_support::{Metric, MetricHint, MetricStream, Polarity};
3756        static PAYLOAD: crate::test_support::Payload = crate::test_support::Payload {
3757            name: "hinted",
3758            kind: crate::test_support::PayloadKind::Binary("x"),
3759            output: crate::test_support::OutputFormat::Json,
3760            default_args: &[],
3761            default_checks: &[],
3762            // Out-of-order with the metric slice below so a naive
3763            // position-based lookup would miss.
3764            metrics: &[
3765                MetricHint {
3766                    name: "lat_ns",
3767                    polarity: Polarity::LowerBetter,
3768                    unit: "ns",
3769                },
3770                MetricHint {
3771                    name: "iops",
3772                    polarity: Polarity::HigherBetter,
3773                    unit: "iops",
3774                },
3775            ],
3776            include_files: &[],
3777            uses_parent_pgrp: false,
3778            known_flags: None,
3779        };
3780        let mut ms = vec![
3781            Metric {
3782                name: "iops".into(),
3783                value: 1.0,
3784                polarity: Polarity::Unknown,
3785                unit: String::new(),
3786                stream: MetricStream::Stdout,
3787            },
3788            Metric {
3789                name: "unhinted".into(),
3790                value: 2.0,
3791                polarity: Polarity::Unknown,
3792                unit: String::new(),
3793                stream: MetricStream::Stdout,
3794            },
3795            Metric {
3796                name: "lat_ns".into(),
3797                value: 3.0,
3798                polarity: Polarity::Unknown,
3799                unit: String::new(),
3800                stream: MetricStream::Stdout,
3801            },
3802        ];
3803        resolve_polarities(&mut ms, &PAYLOAD);
3804        // iops hinted → HigherBetter / "iops".
3805        assert_eq!(ms[0].polarity, Polarity::HigherBetter);
3806        assert_eq!(ms[0].unit, "iops");
3807        // unhinted stays Unknown + empty.
3808        assert_eq!(ms[1].polarity, Polarity::Unknown);
3809        assert_eq!(ms[1].unit, "");
3810        // lat_ns hinted → LowerBetter / "ns".
3811        assert_eq!(ms[2].polarity, Polarity::LowerBetter);
3812        assert_eq!(ms[2].unit, "ns");
3813    }
3814
3815    /// Empty hints or empty metrics are a fast-path — the HashMap
3816    /// build is skipped entirely. Pins the no-op invariant so a
3817    /// regression can't accidentally materialize an empty map for
3818    /// zero metrics on every hot-path call.
3819    /// When the payload declares two MetricHints with the same
3820    /// name, the HashMap build keeps the LAST insertion. The test
3821    /// pins that behavior so a future switch to a multimap or to
3822    /// first-wins semantics surfaces here. First-wins would be
3823    /// surprising: users who copy-paste a hint to tweak it expect
3824    /// the new value.
3825    #[test]
3826    fn resolve_polarities_duplicate_hint_names_last_wins() {
3827        use crate::test_support::{Metric, MetricHint, MetricStream, Polarity};
3828        static PAYLOAD: crate::test_support::Payload = crate::test_support::Payload {
3829            name: "dup_hints",
3830            kind: crate::test_support::PayloadKind::Binary("x"),
3831            output: crate::test_support::OutputFormat::Json,
3832            default_args: &[],
3833            default_checks: &[],
3834            metrics: &[
3835                MetricHint {
3836                    name: "iops",
3837                    polarity: Polarity::HigherBetter,
3838                    unit: "iops",
3839                },
3840                MetricHint {
3841                    name: "iops",
3842                    polarity: Polarity::LowerBetter,
3843                    unit: "overridden",
3844                },
3845            ],
3846            include_files: &[],
3847            uses_parent_pgrp: false,
3848            known_flags: None,
3849        };
3850        let mut ms = vec![Metric {
3851            name: "iops".into(),
3852            value: 1.0,
3853            polarity: Polarity::Unknown,
3854            unit: String::new(),
3855            stream: MetricStream::Stdout,
3856        }];
3857        resolve_polarities(&mut ms, &PAYLOAD);
3858        // Second declaration wins (HashMap last-insertion semantics).
3859        assert_eq!(ms[0].polarity, Polarity::LowerBetter);
3860        assert_eq!(ms[0].unit, "overridden");
3861    }
3862
3863    /// When the metric slice has duplicate names (e.g. a payload
3864    /// emitting the same dotted path twice in one run), the hint
3865    /// is applied to each occurrence. Each is a distinct Metric
3866    /// value in the sidecar; both must carry the hinted polarity +
3867    /// unit so downstream regression reports are consistent.
3868    #[test]
3869    fn resolve_polarities_duplicate_metric_names_each_gets_hint() {
3870        use crate::test_support::{Metric, MetricHint, MetricStream, Polarity};
3871        static PAYLOAD: crate::test_support::Payload = crate::test_support::Payload {
3872            name: "dup_metrics",
3873            kind: crate::test_support::PayloadKind::Binary("x"),
3874            output: crate::test_support::OutputFormat::Json,
3875            default_args: &[],
3876            default_checks: &[],
3877            metrics: &[MetricHint {
3878                name: "iops",
3879                polarity: Polarity::HigherBetter,
3880                unit: "iops",
3881            }],
3882            include_files: &[],
3883            uses_parent_pgrp: false,
3884            known_flags: None,
3885        };
3886        let mut ms = vec![
3887            Metric {
3888                name: "iops".into(),
3889                value: 1.0,
3890                polarity: Polarity::Unknown,
3891                unit: String::new(),
3892                stream: MetricStream::Stdout,
3893            },
3894            Metric {
3895                name: "iops".into(),
3896                value: 2.0,
3897                polarity: Polarity::Unknown,
3898                unit: String::new(),
3899                stream: MetricStream::Stdout,
3900            },
3901        ];
3902        resolve_polarities(&mut ms, &PAYLOAD);
3903        for m in &ms {
3904            assert_eq!(m.polarity, Polarity::HigherBetter);
3905            assert_eq!(m.unit, "iops");
3906        }
3907    }
3908
3909    #[test]
3910    fn resolve_polarities_empty_inputs_are_noop() {
3911        use crate::test_support::{Metric, MetricStream, Polarity};
3912        static NO_HINTS: crate::test_support::Payload = crate::test_support::Payload {
3913            name: "no_hints",
3914            kind: crate::test_support::PayloadKind::Binary("x"),
3915            output: crate::test_support::OutputFormat::Json,
3916            default_args: &[],
3917            default_checks: &[],
3918            metrics: &[],
3919            include_files: &[],
3920            uses_parent_pgrp: false,
3921            known_flags: None,
3922        };
3923        let mut ms = vec![Metric {
3924            name: "anything".into(),
3925            value: 1.0,
3926            polarity: Polarity::Unknown,
3927            unit: String::new(),
3928            stream: MetricStream::Stdout,
3929        }];
3930        resolve_polarities(&mut ms, &NO_HINTS);
3931        assert_eq!(ms[0].polarity, Polarity::Unknown);
3932        assert_eq!(ms[0].unit, "");
3933
3934        // Empty metrics list — also a fast-path no-op, just pin it
3935        // doesn't panic / over-allocate.
3936        let mut empty: Vec<Metric> = vec![];
3937        resolve_polarities(&mut empty, &NO_HINTS);
3938        assert!(empty.is_empty());
3939    }
3940
3941    /// In host (test) context the bulk port is not open and
3942    /// `is_guest()` is false, so the emit must NOT write — it returns
3943    /// `false` via the `write_msg` -> `assert_guest_context`
3944    /// early-return. Asserting the `false` return pins the
3945    /// observable no-op (no frame written) rather than merely that
3946    /// the call did not panic.
3947    #[test]
3948    fn emit_payload_metrics_returns_false_in_host_context() {
3949        let pm = PayloadMetrics {
3950            payload_index: 0,
3951            metrics: Vec::new(),
3952            exit_code: 0,
3953        };
3954        assert!(
3955            !emit_payload_metrics(&pm),
3956            "host-context emit must report no write (false) — the \
3957             bulk port is closed and assert_guest_context bails"
3958        );
3959    }
3960
3961    // -- PayloadHandle double-consume returns Err, not panic --
3962
3963    /// After `try_wait()` returns `Ok(Some(..))` (terminal branch
3964    /// that takes the child), a subsequent `try_wait()` on the same
3965    /// handle must return `Err` instead of panicking. Previously
3966    /// the implementation unwrapped `self.child.as_mut()` with a
3967    /// panicking `.expect(...)`.
3968    #[test]
3969    fn try_wait_after_terminal_returns_err() {
3970        with_ctx("/nonexistent", |ctx| {
3971            let mut handle = PayloadRun::new(ctx, &TRUE_BIN)
3972                .spawn()
3973                .expect("spawn /bin/true");
3974            // First terminal: /bin/true exits immediately; spin until
3975            // try_wait returns Some.
3976            for _ in 0..100 {
3977                if handle.try_wait().expect("try_wait").is_some() {
3978                    break;
3979                }
3980                std::thread::sleep(std::time::Duration::from_millis(10));
3981            }
3982            // Second call must not panic — expect Err describing the
3983            // consumed state.
3984            let err = handle
3985                .try_wait()
3986                .expect_err("second try_wait on consumed handle must be Err");
3987            let msg = format!("{err:#}");
3988            assert!(
3989                msg.contains("already consumed") && msg.contains("true_bin"),
3990                "error must name the handle + misuse, got: {msg}"
3991            );
3992        });
3993    }
3994
3995    /// Calling `wait()` after `try_wait()` has consumed the child
3996    /// must Err rather than panic. Test pairs with
3997    /// `try_wait_after_terminal_returns_err`: same state, different
3998    /// terminal method.
3999    #[test]
4000    fn wait_after_try_wait_consumed_returns_err() {
4001        with_ctx("/nonexistent", |ctx| {
4002            let mut handle = PayloadRun::new(ctx, &TRUE_BIN)
4003                .spawn()
4004                .expect("spawn /bin/true");
4005            for _ in 0..100 {
4006                if handle.try_wait().expect("try_wait").is_some() {
4007                    break;
4008                }
4009                std::thread::sleep(std::time::Duration::from_millis(10));
4010            }
4011            // Child is now taken; wait() must return Err, not panic.
4012            let err = handle
4013                .wait()
4014                .expect_err("wait() on consumed handle must return Err");
4015            let msg = format!("{err:#}");
4016            assert!(
4017                msg.contains("already consumed") && msg.contains("true_bin"),
4018                "error must name the handle + misuse, got: {msg}"
4019            );
4020        });
4021    }
4022
4023    /// Calling `kill()` after `try_wait()` has consumed the child
4024    /// must Err rather than panic.
4025    #[test]
4026    fn kill_after_try_wait_consumed_returns_err() {
4027        with_ctx("/nonexistent", |ctx| {
4028            let mut handle = PayloadRun::new(ctx, &TRUE_BIN)
4029                .spawn()
4030                .expect("spawn /bin/true");
4031            for _ in 0..100 {
4032                if handle.try_wait().expect("try_wait").is_some() {
4033                    break;
4034                }
4035                std::thread::sleep(std::time::Duration::from_millis(10));
4036            }
4037            let err = handle
4038                .kill()
4039                .expect_err("kill() on consumed handle must return Err");
4040            let msg = format!("{err:#}");
4041            assert!(
4042                msg.contains("already consumed") && msg.contains("true_bin"),
4043                "error must name the handle + misuse, got: {msg}"
4044            );
4045        });
4046    }
4047
4048    // -- stdout-primary / stderr-fallback evaluation --
4049
4050    const JSON_PAYLOAD: Payload = Payload {
4051        name: "json_payload",
4052        kind: PayloadKind::Binary("json_payload"),
4053        output: OutputFormat::Json,
4054        default_args: &[],
4055        default_checks: &[],
4056        metrics: &[],
4057        include_files: &[],
4058        uses_parent_pgrp: false,
4059        known_flags: None,
4060    };
4061
4062    /// Well-behaved case: stdout carries the JSON document; stderr
4063    /// carries banner noise the extractor must NOT see. Merging the
4064    /// streams would pull the banner into the metric blob; the
4065    /// fallback contract keeps stdout canonical.
4066    #[test]
4067    fn evaluate_prefers_stdout_when_stdout_yields_metrics() {
4068        let output = SpawnOutput {
4069            stdout: r#"{"iops": 500}"#.to_string(),
4070            stderr: "unrelated banner: open fd error (ignore)".to_string(),
4071            exit_code: 0,
4072        };
4073        let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4074        assert_eq!(pm.metrics.len(), 1, "stdout JSON must win");
4075        assert_eq!(pm.metrics[0].name, "iops");
4076        assert_eq!(pm.metrics[0].value, 500.0);
4077    }
4078
4079    /// schbench-style: the payload emits JSON percentiles on stderr,
4080    /// leaves stdout empty. Stdout-primary extraction returns an
4081    /// empty Vec, then the stderr fallback runs and produces the
4082    /// real metrics.
4083    #[test]
4084    fn evaluate_falls_back_to_stderr_when_stdout_empty() {
4085        let output = SpawnOutput {
4086            stdout: String::new(),
4087            stderr: r#"{"latency_ns": 1234}"#.to_string(),
4088            exit_code: 0,
4089        };
4090        let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4091        assert_eq!(pm.metrics.len(), 1, "stderr fallback must fire");
4092        assert_eq!(pm.metrics[0].name, "latency_ns");
4093        assert_eq!(pm.metrics[0].value, 1234.0);
4094    }
4095
4096    /// End-to-end stream-attribution pin for the stderr-fallback
4097    /// branch. When stdout carries no extractable metrics and the
4098    /// fallback pulls the real document from stderr, every emitted
4099    /// metric's `stream` field must tag `MetricStream::Stderr` —
4100    /// NOT `Stdout`. The attribution is what lets downstream review
4101    /// tools filter stderr-sourced metrics (well-behaved payloads
4102    /// keep stdout canonical; an all-stderr metric set is a review
4103    /// hint that the payload may be violating the channel
4104    /// convention). A regression that stamped `Stdout` on every
4105    /// Metric regardless of which stream it came from would silence that review
4106    /// signal without changing the metric values themselves — this
4107    /// test pins the attribution end-to-end so the regression
4108    /// cannot slip past the existing value-only asserts on the
4109    /// sibling fallback tests.
4110    ///
4111    /// Pairs three fallback shapes in one test: empty stdout, prose
4112    /// stdout, and valid-JSON-no-numeric-leaves stdout. The three
4113    /// share one fallback decision (`metrics.is_empty()` after
4114    /// stdout attempt), so their attribution invariant is identical;
4115    /// one test exercises all three to close the fallback-shape
4116    /// coverage gap for the stream field specifically.
4117    /// Positive control for the stream-attribution pin: when
4118    /// stdout carries valid JSON that extracts cleanly, every
4119    /// emitted metric's `stream` must tag `MetricStream::Stdout`
4120    /// — NOT `Stderr`. The sibling
4121    /// `stderr_fallback_tags_metrics_with_metric_stream_stderr`
4122    /// covers the fallback (negative) side; this test closes the
4123    /// symmetry gap. A regression that unconditionally stamped
4124    /// `Stderr` on every Metric (or swapped the two
4125    /// unconditionally) would trip the fallback test's value-
4126    /// agnostic `== Stderr` assertion OR this test's inverse
4127    /// `== Stdout` assertion — at least one of the two paths
4128    /// has to change its stream tag direction to hide the bug.
4129    ///
4130    /// Exercises the happy path with both a minimal JSON object
4131    /// and a multi-key JSON object, proving the attribution is
4132    /// per-metric rather than per-document. A regression that
4133    /// attributed based on document-level shape (e.g. "stream =
4134    /// Stderr if multi-key") would fail on the second fixture.
4135    #[test]
4136    fn stdout_primary_tags_metrics_with_metric_stream_stdout() {
4137        use crate::test_support::MetricStream;
4138
4139        for (label, stdout) in [
4140            ("single-key", r#"{"iops": 4242}"#.to_string()),
4141            (
4142                "multi-key",
4143                r#"{"iops": 1000, "latency_us": 42, "runs": 3}"#.to_string(),
4144            ),
4145        ] {
4146            let output = SpawnOutput {
4147                stdout,
4148                // stderr carries a distinct value so a regression
4149                // that merged the streams (or used stderr despite
4150                // stdout winning) would surface a wrong-valued
4151                // metric here alongside the wrong stream tag.
4152                stderr: r#"{"iops": 9999999}"#.to_string(),
4153                exit_code: 0,
4154            };
4155            let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4156            assert!(
4157                !pm.metrics.is_empty(),
4158                "[{label}] stdout-primary must produce metrics",
4159            );
4160            for m in &pm.metrics {
4161                assert_eq!(
4162                    m.stream,
4163                    MetricStream::Stdout,
4164                    "[{label}] stdout-extracted metric `{name}` must \
4165                     carry MetricStream::Stdout; got stream={stream:?}. \
4166                     A regression that mis-tagged stdout-sourced \
4167                     metrics as Stderr (or merged the streams) would \
4168                     trip here — the stderr-fallback sibling test \
4169                     covers the inverse direction.",
4170                    name = m.name,
4171                    stream = m.stream,
4172                );
4173            }
4174            // Stream-independence: the `iops` value MUST come from
4175            // stdout (4242 / 1000), not stderr (9999999). A
4176            // regression that pulled from the wrong stream would
4177            // both mis-tag AND mis-value, but the value check is
4178            // the ground-truth that the stream tag then describes.
4179            let iops = pm
4180                .metrics
4181                .iter()
4182                .find(|m| m.name == "iops")
4183                .expect("iops metric must be present");
4184            assert!(
4185                iops.value < 9_000_000.0,
4186                "[{label}] iops value {val} must come from stdout \
4187                 (< 9M) not stderr (9999999); a value from stderr \
4188                 would prove the test's stream tag is accidentally \
4189                 correct because the merge went the wrong way",
4190                val = iops.value,
4191            );
4192        }
4193    }
4194
4195    #[test]
4196    fn stderr_fallback_tags_metrics_with_metric_stream_stderr() {
4197        use crate::test_support::MetricStream;
4198
4199        for (label, stdout) in [
4200            ("empty-stdout", String::new()),
4201            (
4202                "prose-stdout",
4203                "no json here, just prose from a banner line\n".to_string(),
4204            ),
4205            (
4206                "valid-json-no-numeric-leaves-stdout",
4207                r#"{"status": "ok", "ready": true, "note": null}"#.to_string(),
4208            ),
4209        ] {
4210            let output = SpawnOutput {
4211                stdout,
4212                stderr: r#"{"iops": 4242}"#.to_string(),
4213                exit_code: 0,
4214            };
4215            let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4216            assert_eq!(
4217                pm.metrics.len(),
4218                1,
4219                "[{label}] stderr fallback must produce exactly one metric",
4220            );
4221            assert_eq!(
4222                pm.metrics[0].stream,
4223                MetricStream::Stderr,
4224                "[{label}] fallback-extracted metric must carry MetricStream::Stderr \
4225                 so downstream review tooling can distinguish stream origin; \
4226                 got stream={:?}",
4227                pm.metrics[0].stream,
4228            );
4229        }
4230    }
4231
4232    /// Stdout present but unparseable (not-JSON prose); stderr
4233    /// carries the real document. `extract_metrics` returns `Vec`
4234    /// empty for malformed stdout, so the fallback runs against
4235    /// stderr and recovers the metrics. Pins that "non-empty stdout
4236    /// that yields no metrics" still triggers the retry — the
4237    /// stdout-primary contract gates on the result, not on emptiness.
4238    #[test]
4239    fn evaluate_falls_back_to_stderr_when_stdout_yields_no_metrics() {
4240        let output = SpawnOutput {
4241            stdout: "no json here, just prose from a banner line\n".to_string(),
4242            stderr: r#"{"throughput": 42}"#.to_string(),
4243            exit_code: 0,
4244        };
4245        let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4246        assert_eq!(
4247            pm.metrics.len(),
4248            1,
4249            "stderr fallback must fire on empty result"
4250        );
4251        assert_eq!(pm.metrics[0].name, "throughput");
4252        assert_eq!(pm.metrics[0].value, 42.0);
4253    }
4254
4255    /// Stdout is valid JSON but contains only non-numeric leaves
4256    /// (strings, bools, nulls). `walk_json_leaves` at
4257    /// src/test_support/metrics.rs skips non-numeric leaves, so
4258    /// `extract_metrics` returns `Ok(vec![])` — a SUCCESSFUL parse
4259    /// with zero metrics. This is distinct from the
4260    /// "unparseable prose" case (`evaluate_falls_back_to_stderr_when_stdout_yields_no_metrics`
4261    /// above): that path fails to find any JSON document at all.
4262    /// The fallback condition (`evaluate`'s
4263    /// `if metrics.is_empty() && !output.stderr.is_empty()` gate)
4264    /// gates on `metrics.is_empty()`, not on parse success, so both
4265    /// paths must fall back to stderr. This test pins that: the
4266    /// fallback must not surface the empty stdout set as the
4267    /// result, and the string/bool/null leaves from stdout must
4268    /// not leak into the returned metrics (they can't — the walker
4269    /// never emitted them — but a future refactor that concatenated
4270    /// streams or merged results could regress this).
4271    #[test]
4272    fn evaluate_falls_back_when_stdout_json_has_no_numeric_leaves() {
4273        let output = SpawnOutput {
4274            stdout: r#"{"status": "ok", "ready": true, "note": null}"#.to_string(),
4275            stderr: r#"{"iops": 9001}"#.to_string(),
4276            exit_code: 0,
4277        };
4278        let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4279        assert_eq!(
4280            pm.metrics.len(),
4281            1,
4282            "stderr fallback must fire when stdout parses but has \
4283             no numeric leaves; got metrics: {:?}",
4284            pm.metrics,
4285        );
4286        assert_eq!(pm.metrics[0].name, "iops");
4287        assert_eq!(pm.metrics[0].value, 9001.0);
4288        // No stray string/bool/null names leaked in from stdout.
4289        for m in &pm.metrics {
4290            assert!(
4291                !matches!(m.name.as_str(), "status" | "ready" | "note"),
4292                "non-numeric stdout leaf {:?} leaked into metrics",
4293                m.name,
4294            );
4295        }
4296    }
4297
4298    /// Inverse of the above: both streams parse to JSON with no
4299    /// numeric leaves. Stdout extracts to `Ok(vec![])`, fallback
4300    /// fires, stderr also extracts to `Ok(vec![])`. Final metric
4301    /// set must be empty — not a synthetic pseudo-metric, not a
4302    /// silent merge of the two empty results with added string
4303    /// keys. Guards against a fallback refactor that might
4304    /// misinterpret "both empty" as "degenerate, emit a sentinel".
4305    #[test]
4306    fn evaluate_returns_empty_when_both_streams_have_no_numeric_leaves() {
4307        let output = SpawnOutput {
4308            stdout: r#"{"phase": "warmup"}"#.to_string(),
4309            stderr: r#"{"phase": "shutdown"}"#.to_string(),
4310            exit_code: 0,
4311        };
4312        let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4313        assert!(
4314            pm.metrics.is_empty(),
4315            "both-streams-non-numeric must produce no metrics; \
4316             got: {:?}",
4317            pm.metrics,
4318        );
4319    }
4320
4321    /// Both streams empty ⇒ no metrics; the fallback guard
4322    /// (`!output.stderr.is_empty()`) skips the second call and the
4323    /// extractor is invoked exactly once against empty stdout.
4324    #[test]
4325    fn evaluate_returns_empty_metrics_on_empty_stdout_and_stderr() {
4326        let output = SpawnOutput {
4327            stdout: String::new(),
4328            stderr: String::new(),
4329            exit_code: 0,
4330        };
4331        let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4332        assert!(pm.metrics.is_empty(), "both-empty must produce no metrics");
4333        assert_eq!(pm.exit_code, 0);
4334    }
4335
4336    /// Multi-process payloads (schbench worker mode, stress-ng, fio)
4337    /// fork descendants that keep stdout/stderr open past the head
4338    /// process. Without a process-group kill, `wait_and_capture`
4339    /// would block on a pipe that never EOFs and the test would
4340    /// either hang or time out without metrics.
4341    ///
4342    /// The payload `/bin/sh -c 'sleep 60 & exec sleep 60'` uses the
4343    /// shell's head process to exec into `sleep 60` (pid == pgid)
4344    /// while a background `sleep 60` descendant inherits the pgid.
4345    /// A single-process SIGKILL would leave the background sleeper
4346    /// alive; `killpg` must reach it.
4347    ///
4348    /// SIGKILL delivery may lag the caller. The bounded live-member
4349    /// check accepts a dead zombie that is awaiting an outer
4350    /// subreaper, but still fails if any member can execute.
4351    #[cfg(unix)]
4352    #[test]
4353    fn kill_reaps_fork_descendants_via_process_group() {
4354        with_ctx("/nonexistent", |ctx| {
4355            const MULTI_SLEEPER: Payload = Payload {
4356                name: "multi_sleeper",
4357                kind: PayloadKind::Binary("/bin/sh"),
4358                output: crate::test_support::OutputFormat::ExitCode,
4359                default_args: &["-c", "sleep 60 & exec sleep 60"],
4360                default_checks: &[],
4361                metrics: &[],
4362                include_files: &[],
4363                uses_parent_pgrp: false,
4364                known_flags: None,
4365            };
4366            let handle = PayloadRun::new(ctx, &MULTI_SLEEPER)
4367                .spawn()
4368                .expect("spawn multi-sleeper");
4369            // The pgid equals the head child's pid. Capture it via the
4370            // public `pid()` accessor so the test does not reach into the
4371            // private `child` field.
4372            let pgid = libc::pid_t::try_from(handle.pid().expect("child still present"))
4373                .expect("child pid fits in pid_t");
4374            let (_, _) = handle.kill().expect("kill+reap");
4375            wait_for_process_group_termination(
4376                pgid,
4377                std::time::Duration::from_secs(30),
4378                "explicit kill+reap",
4379            );
4380        });
4381    }
4382
4383    /// Drop path of [`PayloadHandle`]: a handle that falls out of
4384    /// scope WITHOUT any consuming call (no `wait`, no `kill`, no
4385    /// `try_wait`) must still SIGKILL the whole process group via
4386    /// `kill_payload_process_group`. Without the Drop sweep,
4387    /// multi-process payloads whose head exits while descendants
4388    /// linger would leak their leader pid and keep descendants
4389    /// alive on init, polluting later tests with stray children
4390    /// holding file descriptors.
4391    ///
4392    /// Mirrors `kill_reaps_fork_descendants_via_process_group`
4393    /// (the explicit-`kill()` counterpart) but drops the handle
4394    /// instead of calling kill — pins the Drop implementation's
4395    /// killpg route against the same backgrounded-sleeper shape.
4396    #[cfg(unix)]
4397    #[test]
4398    fn drop_kills_fork_descendants_via_process_group() {
4399        with_ctx("/nonexistent", |ctx| {
4400            const MULTI_SLEEPER: Payload = Payload {
4401                name: "multi_sleeper_drop",
4402                kind: PayloadKind::Binary("/bin/sh"),
4403                output: crate::test_support::OutputFormat::ExitCode,
4404                default_args: &["-c", "sleep 60 & exec sleep 60"],
4405                default_checks: &[],
4406                metrics: &[],
4407                include_files: &[],
4408                uses_parent_pgrp: false,
4409                known_flags: None,
4410            };
4411            let handle = PayloadRun::new(ctx, &MULTI_SLEEPER)
4412                .spawn()
4413                .expect("spawn multi-sleeper");
4414            // Capture the pgid via the public `pid()` accessor before
4415            // dropping, so we can probe the group after the handle
4416            // goes out of scope.
4417            let pgid = libc::pid_t::try_from(handle.pid().expect("child still present"))
4418                .expect("child pid fits in pid_t");
4419            // Drop (no wait/kill/try_wait). The Drop impl at
4420            // src/scenario/payload_run.rs routes through
4421            // `kill_payload_process_group` + `child.wait()`.
4422            drop(handle);
4423            wait_for_process_group_termination(
4424                pgid,
4425                std::time::Duration::from_secs(30),
4426                "PayloadHandle drop",
4427            );
4428        });
4429    }
4430
4431    /// `uses_parent_pgrp = true` SKIPS the `process_group(0)` call
4432    /// in `build_command`, so the child inherits the test
4433    /// process's pgid instead of becoming its own pgrp leader.
4434    /// Spawn a sleeping binary via a Payload with the flag set,
4435    /// `getpgid` the child's pid, and assert it equals the
4436    /// parent's pgid — that pairs the "opt-out" directive with
4437    /// the observable behaviour.
4438    #[cfg(unix)]
4439    #[test]
4440    fn payload_uses_parent_pgrp_opts_out_of_process_group() {
4441        with_ctx("/nonexistent", |ctx| {
4442            const PARENT_PGRP_SLEEPER: Payload = Payload {
4443                name: "parent_pgrp_sleeper",
4444                kind: PayloadKind::Binary("/bin/sleep"),
4445                output: crate::test_support::OutputFormat::ExitCode,
4446                default_args: &["60"],
4447                default_checks: &[],
4448                metrics: &[],
4449                include_files: &[],
4450                uses_parent_pgrp: true,
4451                known_flags: None,
4452            };
4453            let handle = PayloadRun::new(ctx, &PARENT_PGRP_SLEEPER)
4454                .spawn()
4455                .expect("spawn opt-out sleeper");
4456            let child_pid = libc::pid_t::try_from(handle.pid().expect("child alive"))
4457                .expect("child pid fits in pid_t");
4458            // SAFETY: getpgid(pid) is a pure lookup with no side
4459            // effects beyond returning the queried pid's pgid (or -1
4460            // + errno on failure).
4461            let child_pgid = unsafe { libc::getpgid(child_pid) };
4462            // SAFETY: getpgid(0) returns the CURRENT process's pgid
4463            // and cannot fail.
4464            let parent_pgid = unsafe { libc::getpgid(0) };
4465            assert!(child_pgid > 0, "getpgid(child) failed: {child_pgid}");
4466            assert_eq!(
4467                child_pgid, parent_pgid,
4468                "uses_parent_pgrp=true payload must inherit the \
4469                 parent's pgid (child_pgid={child_pgid}, \
4470                 parent_pgid={parent_pgid}); a mismatch means \
4471                 `build_command` still called `process_group(0)` \
4472                 despite the opt-out",
4473            );
4474            // kill() on a handle whose child is not a pgrp leader
4475            // still reaps normally — kill_payload_process_group
4476            // falls back to single-pid SIGKILL. Consume the handle
4477            // so the sleeper doesn't outlive the test; a silent
4478            // failure here would mask the test's own regression
4479            // (e.g. a broken kill path that leaks sleepers).
4480            let _ = handle.kill().expect("kill opt-out sleeper");
4481        });
4482    }
4483
4484    /// `wait_with_deadline` timeout kills the whole process group
4485    /// via killpg + single-pid SIGKILL. Spawn a multi-process
4486    /// shell, drive `wait_with_deadline` with a 500 ms budget
4487    /// (so the whole test fits inside the 30s-slack nextest
4488    /// budget without standing up a whole scenario) and probes the
4489    /// pgid after the deadline fires and proves no live member remains.
4490    #[cfg(unix)]
4491    #[test]
4492    fn wait_with_deadline_timeout_kills_process_group() {
4493        use std::os::unix::process::CommandExt;
4494        let mut child = std::process::Command::new("/bin/sh")
4495            .args(["-c", "sleep 60 & exec sleep 60"])
4496            .stdout(std::process::Stdio::piped())
4497            .stderr(std::process::Stdio::piped())
4498            .process_group(0)
4499            .spawn()
4500            .expect("spawn multi-sleeper");
4501        let pgid = libc::pid_t::try_from(child.id()).expect("child pid fits in pid_t");
4502        let start = std::time::Instant::now();
4503        let out = wait_with_deadline(
4504            &mut child,
4505            std::time::Duration::from_millis(500),
4506            "multi_sleeper_timeout",
4507            false,
4508        )
4509        .expect("wait_with_deadline returns Ok on timeout");
4510        let elapsed = start.elapsed();
4511        // Timeout must actually have elapsed — if the function
4512        // returns almost instantly, the pidfd/epoll loop is
4513        // short-circuiting on an unrelated signal rather than
4514        // waiting for the 500 ms deadline.
4515        assert!(
4516            elapsed >= std::time::Duration::from_millis(400),
4517            "wait_with_deadline returned after only {elapsed:?}; \
4518             deadline was 500 ms — check the epoll loop is honoring \
4519             the timeout rather than unblocking on an unrelated event",
4520        );
4521        // The drain result must be captured even on timeout.
4522        // After SIGKILL the child's std::process::ExitStatus has
4523        // no numeric code (killed by signal, `status.code()`
4524        // returns None), so `wait_and_capture` defaults to -1 at
4525        // src/scenario/payload_run.rs per the `unwrap_or(-1)`
4526        // fallback in its status-code read. Pin that contract —
4527        // a future refactor that surfaces the signal number as
4528        // the exit_code would regress this.
4529        assert_eq!(out.exit_code, -1);
4530        wait_for_process_group_termination(
4531            pgid,
4532            std::time::Duration::from_secs(30),
4533            "wait_with_deadline timeout",
4534        );
4535    }
4536
4537    /// [`spawn_error_context`] is the sole place the spawn-error
4538    /// surface is shaped. An `ErrorKind::NotFound` must grow the full
4539    /// remediation chain (include-files for CLI invocations,
4540    /// pre-install for `#[ktstr_test]` entries); every other errno
4541    /// MUST keep the minimal `"spawn '<binary>'"` context so the
4542    /// underlying `io::Error` chain surfaces unchanged. Pin both
4543    /// directions so a regression that (a) swallows the NotFound
4544    /// remediation or (b) sprays the remediation across unrelated
4545    /// errno paths surfaces here.
4546    #[test]
4547    fn spawn_error_context_enoent_attaches_remediation() {
4548        let err = std::io::Error::from_raw_os_error(libc::ENOENT);
4549        assert_eq!(err.kind(), std::io::ErrorKind::NotFound);
4550        let wrapped = super::spawn_error_context(err, "fio");
4551        let rendered = format!("{wrapped:#}");
4552        // Binary name still appears so `grep fio` still finds the error.
4553        assert!(rendered.contains("spawn 'fio'"), "got: {rendered}");
4554        // Remediation text must surface both mitigation paths.
4555        assert!(
4556            rendered.contains("not found on guest PATH"),
4557            "ENOENT branch must name the PATH miss: {rendered}"
4558        );
4559        assert!(
4560            rendered.contains("-i fio") || rendered.contains("--include-files fio"),
4561            "ENOENT branch must name the `-i <binary>` remediation: {rendered}"
4562        );
4563        assert!(
4564            rendered.contains("#[ktstr_test]"),
4565            "ENOENT branch must name the ktstr_test pre-install remediation: {rendered}"
4566        );
4567    }
4568
4569    #[test]
4570    fn spawn_error_context_non_enoent_keeps_minimal_context() {
4571        // EACCES is a representative non-NotFound errno. Any
4572        // remediation text leaking onto this path would mislead
4573        // users who e.g. hit a permission problem — the remediation
4574        // paths above (include-files, pre-install) are orthogonal
4575        // to the failure mode. Pin the absence.
4576        let err = std::io::Error::from_raw_os_error(libc::EACCES);
4577        assert_ne!(err.kind(), std::io::ErrorKind::NotFound);
4578        let wrapped = super::spawn_error_context(err, "fio");
4579        let rendered = format!("{wrapped:#}");
4580        assert!(rendered.contains("spawn 'fio'"), "got: {rendered}");
4581        assert!(
4582            !rendered.contains("-i fio"),
4583            "non-ENOENT must not leak the `-i` remediation: {rendered}"
4584        );
4585        assert!(
4586            !rendered.contains("--include-files"),
4587            "non-ENOENT must not leak the --include-files remediation: {rendered}"
4588        );
4589        assert!(
4590            !rendered.contains("#[ktstr_test]"),
4591            "non-ENOENT must not leak the ktstr_test remediation: {rendered}"
4592        );
4593        assert!(
4594            !rendered.contains("not found on guest PATH"),
4595            "non-ENOENT must not claim 'not found on PATH': {rendered}"
4596        );
4597    }
4598
4599    // -- cgroup-sync placement protocol --
4600
4601    /// When `cgroup_path` is `None`, `build_command` must return a
4602    /// Command with NO cgroup-sync handles. Regression guard
4603    /// against accidentally wiring the sync for inherited-cgroup
4604    /// placements, where the handshake would produce spurious
4605    /// pipe allocations and a spawn-thread round-trip for every
4606    /// payload run.
4607    #[test]
4608    fn build_command_without_cgroup_returns_no_sync_handles() {
4609        let (_cmd, handles) = super::build_command("/bin/true", &[], None, false).unwrap();
4610        assert!(
4611            handles.is_none(),
4612            "no cgroup_path ⇒ no sync handles — got Some(_)",
4613        );
4614    }
4615
4616    /// When `cgroup` is `Some(_)`, `build_command` must
4617    /// allocate both pipes and populate the cgroup.procs path
4618    /// plus the cgroup_name passed through. The target directory
4619    /// does NOT need to exist at build time — the placement is
4620    /// deferred to `spawn_with_cgroup_sync`, where a failure
4621    /// surfaces through the [`crate::cgroup::CgroupOps`] trait
4622    /// implementation's error context.
4623    #[test]
4624    fn build_command_with_cgroup_returns_sync_handles() {
4625        let fake_cg = std::path::PathBuf::from("/nonexistent/fake-cgroup");
4626        let (_cmd, handles) = super::build_command(
4627            "/bin/true",
4628            &[],
4629            Some(("fake-cg", fake_cg.as_path())),
4630            false,
4631        )
4632        .expect("build_command must defer cgroup-path validation to sync");
4633        let handles = handles.expect("cgroup path ⇒ handles");
4634        assert_eq!(
4635            handles.cgroup_procs_path,
4636            fake_cg.join("cgroup.procs"),
4637            "handles must carry <cg>/cgroup.procs verbatim",
4638        );
4639        assert_eq!(
4640            handles.cgroup_name, "fake-cg",
4641            "handles must carry the user-facing cgroup name verbatim",
4642        );
4643        // Both pipes must have valid fds on both ends (pipe2
4644        // succeeded).
4645        assert!(handles.notify.r_fd() >= 0);
4646        assert!(handles.notify.w_fd() >= 0);
4647        assert!(handles.release.r_fd() >= 0);
4648        assert!(handles.release.w_fd() >= 0);
4649    }
4650
4651    /// `PipePair::new` allocates a fresh pipe on every call;
4652    /// pins the Drop path closes both fds so repeated calls
4653    /// don't leak fd-table entries under test iteration.
4654    #[test]
4655    fn pipe_pair_allocates_fresh_pipe_on_each_call() {
4656        use std::io::{Read, Write};
4657        use std::os::fd::{AsRawFd, FromRawFd};
4658        let a = super::PipePair::new().unwrap();
4659        let b = super::PipePair::new().unwrap();
4660        // Distinct fd pairs.
4661        assert_ne!(a.r_fd(), b.r_fd());
4662        assert_ne!(a.w_fd(), b.w_fd());
4663        // Each pipe is a plumbed byte channel: write one byte
4664        // into A's write end, read it from A's read end.
4665        //
4666        // Drive the roundtrip via std::fs::File so we don't hit
4667        // libc directly in the test.
4668        {
4669            let mut w = unsafe { std::fs::File::from_raw_fd(a.w_fd()) };
4670            w.write_all(&[42u8]).unwrap();
4671            // Detach — the File closes the fd when dropped, but
4672            // we want the OwnedFd on the PipePair to handle it.
4673            std::mem::forget(w);
4674        }
4675        let mut buf = [0u8; 1];
4676        let mut r = unsafe { std::fs::File::from_raw_fd(a.read_fd.as_raw_fd()) };
4677        r.read_exact(&mut buf).unwrap();
4678        assert_eq!(buf[0], 42);
4679        std::mem::forget(r);
4680        // Drop the second pipe explicitly to exercise the Drop path.
4681        drop(b.read_fd);
4682        drop(b.write_fd);
4683    }
4684
4685    /// End-to-end: `drive_cgroup_handshake` reads a pid sent via the
4686    /// notify pipe, writes it to a temp "cgroup.procs" file, and
4687    /// releases the "child" via the release pipe. Exercises the
4688    /// real protocol without requiring a real cgroup — the temp
4689    /// file stands in for `/sys/fs/cgroup/<cg>/cgroup.procs`,
4690    /// whose acceptable write format is `<pid>\n`.
4691    ///
4692    /// Uses a synthetic Command that can't actually reach spawn
4693    /// (`/nonexistent`), but the test only drives the
4694    /// handshake half via a fake `CgroupSyncHandles`; the spawn
4695    /// side is stubbed by running the handshake directly, not
4696    /// through `drive_cgroup_handshake`'s thread wrapper.
4697    #[test]
4698    fn spawn_with_cgroup_sync_writes_pid_and_releases_child() {
4699        use std::io::Read;
4700        use std::os::fd::FromRawFd;
4701
4702        // Stand-in for cgroup.procs in a temp dir. The CgroupManager
4703        // points at `parent_dir`; the cgroup_name is `cg_leaf`, so
4704        // the trait derives `parent_dir/cg_leaf/cgroup.procs` =
4705        // `procs_path` — matches the real production resolution.
4706        let parent_dir = std::env::temp_dir().join(format!("ktstr-cgroup-sync-test-{}", unsafe {
4707            libc::getpid()
4708        }));
4709        std::fs::create_dir_all(&parent_dir).unwrap();
4710        let leaf_dir = parent_dir.join("cg_leaf");
4711        std::fs::create_dir_all(&leaf_dir).unwrap();
4712        let procs_path = leaf_dir.join("cgroup.procs");
4713        std::fs::write(&procs_path, b"").unwrap();
4714
4715        // Allocate two pipe pairs — one notify, one release.
4716        let notify = super::PipePair::new().unwrap();
4717        let release = super::PipePair::new().unwrap();
4718
4719        // Simulate child pre_exec: write pid into notify,
4720        // block on release. Run on a thread so the main test
4721        // thread can drive the handshake without a deadlock.
4722        let child_pid: libc::pid_t = 99999;
4723        let notify_w_fd = notify.w_fd();
4724        let release_r_fd = release.r_fd();
4725        let child_thread = std::thread::spawn(move || {
4726            use std::io::Write;
4727            // Write pid as LE bytes, matching the real pre_exec.
4728            let mut w = unsafe { std::fs::File::from_raw_fd(notify_w_fd) };
4729            w.write_all(&child_pid.to_le_bytes()).unwrap();
4730            drop(w);
4731            // Block on release.
4732            let mut r = unsafe { std::fs::File::from_raw_fd(release_r_fd) };
4733            let mut buf = [0u8; 1];
4734            r.read_exact(&mut buf).unwrap();
4735            assert_eq!(buf[0], 1, "release byte must be 1");
4736            drop(r);
4737        });
4738
4739        // Prevent PipePair's Drop from closing the fds we
4740        // handed to the thread — the thread owns them now.
4741        std::mem::forget(notify.write_fd);
4742        std::mem::forget(release.read_fd);
4743
4744        // Reassemble the handles into the bundle
4745        // `spawn_with_cgroup_sync` consumes. We MUST rebuild the
4746        // PipePair with the remaining fds so its Drop closes
4747        // them on exit.
4748        let notify_r = notify.read_fd;
4749        let release_w = release.write_fd;
4750        let handles = super::CgroupSyncHandles {
4751            notify: super::PipePair {
4752                read_fd: notify_r,
4753                // Dummy fd the drop will close — we need
4754                // something valid. /dev/null satisfies that.
4755                write_fd: unsafe {
4756                    std::os::fd::OwnedFd::from_raw_fd(libc::open(
4757                        c"/dev/null".as_ptr(),
4758                        libc::O_WRONLY,
4759                    ))
4760                },
4761            },
4762            release: super::PipePair {
4763                read_fd: unsafe {
4764                    std::os::fd::OwnedFd::from_raw_fd(libc::open(
4765                        c"/dev/null".as_ptr(),
4766                        libc::O_RDONLY,
4767                    ))
4768                },
4769                write_fd: release_w,
4770            },
4771            cgroup_name: "cg_leaf".to_string(),
4772            cgroup_procs_path: procs_path.clone(),
4773        };
4774
4775        // CgroupManager.parent_path = parent_dir, so
4776        // place_task_during_handshake("cg_leaf", pid) targets
4777        // parent_dir/cg_leaf/cgroup.procs = procs_path.
4778        let mgr = crate::cgroup::CgroupManager::new(parent_dir.to_str().unwrap());
4779
4780        // Drive the handshake on the main thread.
4781        let returned_pid = super::spawn_with_cgroup_sync(handles, &mgr).unwrap();
4782        assert_eq!(
4783            returned_pid, child_pid,
4784            "spawn_with_cgroup_sync must return the pid it read \
4785             from the notify pipe",
4786        );
4787
4788        // The child thread must complete after the release byte
4789        // arrives — join here and capture any panic propagation.
4790        child_thread
4791            .join()
4792            .expect("child thread completes after release");
4793
4794        // The temp cgroup.procs file must now contain the pid
4795        // followed by a newline (`CgroupManager::place_task_during_handshake`
4796        // writes the same `<pid>\n` shape the bare-stdlib path used).
4797        let written = std::fs::read_to_string(&procs_path).unwrap();
4798        assert_eq!(
4799            written,
4800            format!("{child_pid}\n"),
4801            "spawn_with_cgroup_sync must write <pid>\\n to cgroup.procs; \
4802             got {written:?}",
4803        );
4804
4805        // Cleanup.
4806        let _ = std::fs::remove_file(&procs_path);
4807        let _ = std::fs::remove_dir(&leaf_dir);
4808        let _ = std::fs::remove_dir(&parent_dir);
4809    }
4810
4811    /// Failure shape: if the placement trait call cannot reach the
4812    /// target cgroup (parent dir missing), the handshake surfaces
4813    /// an error that names both the cgroup_name the trait received
4814    /// AND the absolute cgroup.procs path the implementation
4815    /// derived. The child thread must NOT hang — it receives EOF
4816    /// on its release read because the handles (carrying the
4817    /// release write end) are dropped on the error path.
4818    #[test]
4819    fn spawn_with_cgroup_sync_errors_on_missing_cgroup_procs_path() {
4820        use std::os::fd::FromRawFd;
4821        let missing_parent = std::path::PathBuf::from("/nonexistent/dir/that/does/not/exist");
4822        let missing_path = missing_parent.join("missing-cg").join("cgroup.procs");
4823
4824        let notify = super::PipePair::new().unwrap();
4825        let release = super::PipePair::new().unwrap();
4826
4827        let child_pid: libc::pid_t = 12345;
4828        let notify_w_fd = notify.w_fd();
4829        let release_r_fd = release.r_fd();
4830        let child_thread = std::thread::spawn(move || -> std::io::Error {
4831            use std::io::{Read, Write};
4832            let mut w = unsafe { std::fs::File::from_raw_fd(notify_w_fd) };
4833            let _ = w.write_all(&child_pid.to_le_bytes());
4834            drop(w);
4835            // Block on release. Expect EOF (read_exact → Err
4836            // when the parent drops its write end on the error
4837            // path).
4838            let mut r = unsafe { std::fs::File::from_raw_fd(release_r_fd) };
4839            let mut buf = [0u8; 1];
4840            let err = r.read_exact(&mut buf).unwrap_err();
4841            drop(r);
4842            err
4843        });
4844
4845        std::mem::forget(notify.write_fd);
4846        std::mem::forget(release.read_fd);
4847
4848        let notify_r = notify.read_fd;
4849        let release_w = release.write_fd;
4850        let handles = super::CgroupSyncHandles {
4851            notify: super::PipePair {
4852                read_fd: notify_r,
4853                write_fd: unsafe {
4854                    std::os::fd::OwnedFd::from_raw_fd(libc::open(
4855                        c"/dev/null".as_ptr(),
4856                        libc::O_WRONLY,
4857                    ))
4858                },
4859            },
4860            release: super::PipePair {
4861                read_fd: unsafe {
4862                    std::os::fd::OwnedFd::from_raw_fd(libc::open(
4863                        c"/dev/null".as_ptr(),
4864                        libc::O_RDONLY,
4865                    ))
4866                },
4867                write_fd: release_w,
4868            },
4869            cgroup_name: "missing-cg".to_string(),
4870            cgroup_procs_path: missing_path.clone(),
4871        };
4872
4873        let mgr = crate::cgroup::CgroupManager::new(missing_parent.to_str().unwrap());
4874        let err = super::spawn_with_cgroup_sync(handles, &mgr).unwrap_err();
4875        let rendered = format!("{err:#}");
4876        assert!(
4877            rendered.contains("missing-cg"),
4878            "error must name the user-facing cgroup name: {rendered}",
4879        );
4880        assert!(
4881            rendered.contains("/nonexistent/dir/that/does/not/exist"),
4882            "error must name the failing path: {rendered}",
4883        );
4884
4885        // Child thread sees EOF because the release write end
4886        // was dropped on the error path.
4887        let child_err = child_thread.join().expect("child thread returns");
4888        assert_eq!(
4889            child_err.kind(),
4890            std::io::ErrorKind::UnexpectedEof,
4891            "child's release read must hit EOF when parent abandons sync; got {child_err}",
4892        );
4893    }
4894
4895    /// **Regression guard for the cross-fork inherited-fd
4896    /// deadlock.** Exercises the REAL fork path: builds a
4897    /// cgroup-sync Command targeting `/bin/true` against a
4898    /// nonexistent cgroup path, then calls
4899    /// [`drive_cgroup_handshake`] (which runs `Command::spawn()`
4900    /// on a thread and drives the parent-side protocol on the
4901    /// main thread).
4902    ///
4903    /// On the error path the parent drops its owned
4904    /// `release.write_fd` when `drive_cgroup_handshake` bails
4905    /// on the missing cgroup.procs. **Without `cgroup_sync_pre_exec`
4906    /// closing the CHILD's inherited copy of `release_write_fd`
4907    /// (Step 0 of the pre_exec protocol)**, the kernel still
4908    /// sees the child's inherited writer alive — the pipe never
4909    /// EOFs — the child's `read(release_read_fd)` blocks forever
4910    /// — `drive_cgroup_handshake` returns the error but the
4911    /// spawn thread's `join()` blocks indefinitely.
4912    ///
4913    /// With the Step 0 close in place, the child's pre_exec
4914    /// read hits EOF (→ EPIPE), the stdlib spawn path writes
4915    /// the errno to its CLOEXEC error channel and tears down
4916    /// the child, the spawn thread's `cmd.spawn()` returns
4917    /// `Err`, and our `join()` completes within the test
4918    /// deadline. A 10s timeout wraps the whole handshake —
4919    /// a regression that re-introduces the inherited-fd leak
4920    /// surfaces as a timeout panic, not a hang.
4921    #[test]
4922    fn drive_cgroup_handshake_does_not_deadlock_on_failing_cgroup_write() {
4923        use std::sync::mpsc;
4924
4925        // Pick a path that cannot possibly open — including a
4926        // guaranteed-missing parent dir so the placement step
4927        // fails hard in `drive_cgroup_handshake`.
4928        let missing_parent =
4929            std::path::PathBuf::from("/nonexistent/ktstr-cgroup-sync-deadlock-parent");
4930        let missing_cgroup = missing_parent.join("deadlock-guard");
4931
4932        // Run the whole exercise in a worker thread so the test
4933        // driver can time-box it: if the child's release read
4934        // ever blocks past the 10s budget we PANIC the timer
4935        // thread rather than hang the test harness.
4936        let (tx, rx) = mpsc::channel::<anyhow::Result<()>>();
4937        let worker = std::thread::spawn(move || {
4938            let (cmd, handles) = super::build_command(
4939                "/bin/true",
4940                &[],
4941                Some(("deadlock-guard", missing_cgroup.as_path())),
4942                false,
4943            )
4944            .expect("build_command");
4945            let handles = handles.expect("handles present when cgroup is Some");
4946            // CgroupManager whose `parent` does not exist, so
4947            // `place_task_during_handshake` will fail on the
4948            // bare `<missing>/<cg>/cgroup.procs` write — the
4949            // same failure shape the deadlock guard targets.
4950            let mgr = crate::cgroup::CgroupManager::new(missing_parent.to_str().unwrap());
4951            let result = super::drive_cgroup_handshake(cmd, handles, "/bin/true", &mgr);
4952            // drive_cgroup_handshake must surface an error
4953            // (the placement write failed) — if it succeeds
4954            // that's also a correctness violation because the
4955            // target directory does not exist.
4956            let err = result.expect_err("handshake against nonexistent cgroup.procs must Err");
4957            let rendered = format!("{err:#}");
4958            assert!(
4959                rendered.contains("cgroup.procs") || rendered.contains("deadlock-guard"),
4960                "handshake error must name the failing step: {rendered}",
4961            );
4962            let _ = tx.send(Ok(()));
4963        });
4964
4965        // 10s deadline — well beyond any legitimate stdlib spawn
4966        // + fork + pre_exec + error-channel latency on a loaded
4967        // CI host, tight enough to flag a real deadlock quickly.
4968        let deadline = std::time::Duration::from_secs(10);
4969        match rx.recv_timeout(deadline) {
4970            Ok(Ok(())) => {
4971                // Worker thread finished cleanly within budget.
4972                worker
4973                    .join()
4974                    .expect("worker thread completes without panic");
4975            }
4976            Ok(Err(e)) => panic!("worker thread reported error: {e:#}"),
4977            Err(mpsc::RecvTimeoutError::Timeout) => panic!(
4978                "drive_cgroup_handshake did not return within \
4979                 {deadline:?} — cross-fork inherited-fd deadlock \
4980                 has regressed. The child's pre_exec is almost \
4981                 certainly blocking on `read(release_read_fd)` \
4982                 because it still holds its own inherited copy of \
4983                 `release_write_fd` open; Step 0 of \
4984                 `cgroup_sync_pre_exec` must `close()` both \
4985                 `notify_read_fd` and `release_write_fd` BEFORE \
4986                 the release-read block, otherwise the kernel \
4987                 never delivers EOF when the parent drops its \
4988                 write end.",
4989            ),
4990            Err(mpsc::RecvTimeoutError::Disconnected) => {
4991                panic!("worker thread disconnected without reporting",)
4992            }
4993        }
4994    }
4995
4996    /// LIFO-drop pin for [`SigchldScope`]'s save-and-restore chain.
4997    ///
4998    /// `SigchldScope::new()` installs `SIG_DFL` and captures the
4999    /// PREVIOUS disposition into `prev`. When two scopes are
5000    /// constructed back-to-back on the same thread, the second
5001    /// scope's `prev` is the FIRST scope's `SIG_DFL` install (not
5002    /// the original disposition). The original disposition lives in
5003    /// the FIRST scope's `prev`.
5004    ///
5005    /// Drop order therefore matters: LIFO (drop second-constructed
5006    /// first) unwinds correctly — second drop restores `SIG_DFL`,
5007    /// first drop restores the original. NON-LIFO (drop
5008    /// first-constructed first) corrupts the disposition: first
5009    /// drop restores the original, second drop overwrites it with
5010    /// `SIG_DFL`, and the rest of the process runs with the wrong
5011    /// SIGCHLD handler.
5012    ///
5013    /// `PayloadHandle` keeps `_sigchld` as the LAST struct field so
5014    /// per-handle drop is always LIFO with respect to the child it
5015    /// guards — the field-order rule documented at the
5016    /// `PayloadHandle` definition. This test pins that LIFO drop of
5017    /// nested scopes preserves the initial disposition by capturing
5018    /// the disposition before, during, and after the scope chain
5019    /// unwinds, then asserting only the LIFO ordering produces the
5020    /// "after == initial" outcome.
5021    ///
5022    /// Implementation note: `libc::signal` returns the previous
5023    /// handler on every call. We use that as the read mechanism —
5024    /// install `SIG_DFL` to read the current handler, then
5025    /// immediately restore it. The read itself is destructive, so
5026    /// the helper has to put the original back before returning.
5027    ///
5028    /// The thread-pin in `SigchldScope::new` requires every
5029    /// construction in the process to come from the SAME thread.
5030    /// Nextest runs each test in its own process (per
5031    /// `.config/nextest.toml`), so this test's thread-of-call wins
5032    /// the pin and other tests' threads are isolated.
5033    #[test]
5034    fn sigchld_scope_lifo_drop_restores_initial_disposition() {
5035        // Read the current SIGCHLD disposition non-destructively by
5036        // saving the value `signal()` returns, then immediately
5037        // re-installing it. SAFETY: same as SigchldScope::new — the
5038        // thread-pin guarantees no other thread is racing the
5039        // process-wide disposition install.
5040        fn read_sigchld() -> libc::sighandler_t {
5041            // Pin the construction thread BEFORE we install — the
5042            // SigchldScope thread-pin is initialized on its first
5043            // `new()` call, but this helper runs before any scope
5044            // is constructed. Without a separate pin step, the
5045            // first scope below would be the one that pins. That
5046            // is fine in practice; the helper just has to use the
5047            // same thread the scopes do, which is the test thread.
5048            let handler = unsafe { libc::signal(libc::SIGCHLD, libc::SIG_DFL) };
5049            // Restore immediately so we don't leak the read-side
5050            // SIG_DFL into the rest of the test. Note: this is
5051            // observably equivalent to "do nothing" if the
5052            // disposition WAS already SIG_DFL, which is the common
5053            // case on the host (the guest init's SIG_IGN flip is
5054            // not active in the unit-test process).
5055            unsafe {
5056                libc::signal(libc::SIGCHLD, handler);
5057            }
5058            handler
5059        }
5060
5061        let initial = read_sigchld();
5062        // Construct nested scopes:
5063        // - outer.prev = initial; outer's new() installs SIG_DFL.
5064        // - inner.prev = SIG_DFL; inner's new() installs SIG_DFL
5065        //   (a no-op since outer already did).
5066        // After both new() calls, the live disposition is SIG_DFL.
5067        let outer = SigchldScope::new();
5068        let inner = SigchldScope::new();
5069        // LIFO drop: inner (constructed second) first.
5070        // - inner.drop() re-installs inner.prev (= SIG_DFL).
5071        //   Live disposition: SIG_DFL.
5072        // - Read confirms SIG_DFL.
5073        // - outer.drop() re-installs outer.prev (= initial).
5074        //   Live disposition: initial.
5075        // - Read confirms initial.
5076        //
5077        // Non-LIFO drop (drop outer first, then inner) would
5078        // produce: outer.drop() restores initial, inner.drop()
5079        // overwrites with SIG_DFL. The final read would see
5080        // SIG_DFL != initial. This test pins LIFO by structuring
5081        // the drops in LIFO order and asserting initial is
5082        // restored at the end. A future refactor that reordered
5083        // struct fields or shuffled drops would trip the final
5084        // assert.
5085        drop(inner);
5086        assert_eq!(
5087            read_sigchld(),
5088            libc::SIG_DFL,
5089            "after inner drop, live disposition must be SIG_DFL — \
5090             inner.prev was outer's SIG_DFL install, not initial",
5091        );
5092        drop(outer);
5093        assert_eq!(
5094            read_sigchld(),
5095            initial,
5096            "after outer drop, live disposition must equal initial \
5097             ({initial:#x}); a non-LIFO drop would leave SIG_DFL \
5098             ({:#x}) leaking into the process",
5099            libc::SIG_DFL,
5100        );
5101    }
5102
5103    /// Drop-side pin for [`PayloadHandle`]: dropping a real handle
5104    /// restores the SIGCHLD disposition.
5105    ///
5106    /// Rust drops struct fields in declaration order. The
5107    /// `PayloadHandle` definition (see the `DROP-ORDER-CRITICAL`
5108    /// comment block above the struct) requires `_sigchld` to drop
5109    /// AFTER `child`: while the child is being reaped on the drop
5110    /// path (via `kill_payload_process_group` + `child.wait()` in
5111    /// `Drop for PayloadHandle`), the SIGCHLD disposition must still
5112    /// be `SIG_DFL` so `waitpid` returns the real exit status instead
5113    /// of failing with `ECHILD` under the guest init's `SIGCHLD =
5114    /// SIG_IGN`. If `_sigchld` were dropped before `child`, its
5115    /// `Drop` would re-install the original (potentially `SIG_IGN`)
5116    /// disposition while `child.wait()` was still in flight and the
5117    /// reap could fail.
5118    ///
5119    /// `PayloadHandle::child` is `Option<std::process::Child>`; the
5120    /// `Drop for PayloadHandle` body gates its kill-and-reap path on
5121    /// `if let Some(mut child) = self.child.take()`, so `child:
5122    /// None` is a valid in-test construction whose handle Drop
5123    /// path is a no-op for the child branch but still drops every
5124    /// field in declaration order. This test constructs a real
5125    /// `PayloadHandle` (not a mirror) with `child: None`, a static
5126    /// `Payload`, an empty `checks` vec, and a real `SigchldScope`
5127    /// and asserts that the SIGCHLD disposition is restored to its
5128    /// initial value after the handle drops. Building the real
5129    /// struct exercises the actual field declaration order — a
5130    /// future refactor that drops `_sigchld` from the field list,
5131    /// renames it, or replaces its type compiles ONLY if this test
5132    /// is updated in lock-step.
5133    ///
5134    /// The thread-pin in `SigchldScope::new` requires every
5135    /// construction in the process to come from the SAME thread.
5136    /// Nextest runs each test in its own process (per
5137    /// `.config/nextest.toml`), so this test's thread-of-call wins
5138    /// the pin and other tests' threads are isolated.
5139    #[test]
5140    fn payload_handle_drop_restores_sigchld_disposition() {
5141        // Read the current SIGCHLD disposition non-destructively by
5142        // saving the value `signal()` returns, then immediately
5143        // re-installing it. SAFETY: same as SigchldScope::new — the
5144        // thread-pin guarantees no other thread is racing the
5145        // process-wide disposition install.
5146        fn read_sigchld() -> libc::sighandler_t {
5147            let handler = unsafe { libc::signal(libc::SIGCHLD, libc::SIG_DFL) };
5148            unsafe {
5149                libc::signal(libc::SIGCHLD, handler);
5150            }
5151            handler
5152        }
5153
5154        let initial = read_sigchld();
5155
5156        // Build a real PayloadHandle. `child: None` means the
5157        // `Drop for PayloadHandle` body's `if let Some(...)` arm is
5158        // not taken, so no kill/reap runs — but every field still
5159        // drops in declaration order, so `_sigchld` (declared last)
5160        // restores the SIGCHLD disposition. TRUE_BIN is a `&'static
5161        // Payload` from this test module.
5162        let handle = PayloadHandle {
5163            child: None,
5164            payload: &TRUE_BIN,
5165            checks: Vec::new(),
5166            _sigchld: SigchldScope::new(),
5167        };
5168
5169        // After SigchldScope::new(), live disposition is SIG_DFL.
5170        assert_eq!(
5171            read_sigchld(),
5172            libc::SIG_DFL,
5173            "SigchldScope::new should have installed SIG_DFL while \
5174             the handle is alive",
5175        );
5176
5177        drop(handle);
5178
5179        // After Drop for PayloadHandle runs, every field has been
5180        // dropped — including _sigchld, whose Drop re-installs the
5181        // captured `prev` (= initial). If a future refactor removed
5182        // _sigchld from the struct (or changed its type to one
5183        // whose Drop does not restore the signal), this assertion
5184        // fails because the live disposition would still be
5185        // SIG_DFL, not initial.
5186        assert_eq!(
5187            read_sigchld(),
5188            initial,
5189            "after dropping a real PayloadHandle, live SIGCHLD \
5190             disposition must equal initial ({initial:#x}); if the \
5191             handle's `_sigchld` field was removed, renamed, or \
5192             retyped, the disposition stays at SIG_DFL ({:#x})",
5193            libc::SIG_DFL,
5194        );
5195    }
5196}