shep-daemon 0.22.0

The supervision engine behind shep: process spawning, restart policy, the log plane, watch and cron restarts, and the RPC server
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
//! The [`MemorySampler`] seam: one read of the machine's process table, and
//! the pure sum that turns it into one sheep's tree total.
//!
//! [`SysinfoSampler`] is the real implementation. A `ScriptedSampler` test
//! fixture replays a scripted sequence of readings for tests that need the
//! table to change between polls. [`tree_rss`] is the pure function both
//! feed; see [`limits`](crate::limits) for why the sum spans the whole
//! process tree.
//!
//! Every item here is public so the bench crate and `tests/external_impls.rs` can use it.

use std::collections::{HashMap, HashSet};
use std::sync::{Mutex, PoisonError};

use sysinfo::{ProcessRefreshKind, ProcessesToUpdate, System};

/// One process's resident-set and CPU-time reading, with the parent link that
/// lets a caller rebuild the tree.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ProcessRss {
    /// The process's own pid.
    pub pid: u32,
    /// Its parent's pid, absent for the roots of the process table.
    pub parent: Option<u32>,
    /// Resident set size in bytes.
    pub bytes: u64,
    /// Accumulated CPU time in CPU-milliseconds, as the OS reports it.
    ///
    /// Cumulative since process start, not a rate: a percentage is a delta
    /// between two readings over the wall time between them, and can exceed
    /// 100 on a multi-core machine.
    pub cpu_ms: u64,
}

/// One process's identity: who it is and whose child it is.
///
/// Separate from [`ProcessRss`] so that type stays `Copy`: adding this
/// `String` field would allocate once per process, every
/// `MEMORY_POLL_INTERVAL` tick, for a field only `shep describe` reads.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProcessIdentity {
    /// The process's own pid.
    pub pid: u32,
    /// Its parent's pid, absent for the roots of the process table.
    pub parent: Option<u32>,
    /// The executable's name as the OS reports it, not its command line.
    pub name: String,
}

/// Reads the machine's process table.
///
/// Synchronous: it is a bounded process-table walk on the enforcer's own
/// task, and an `async fn` here would make the trait dyn-incompatible for
/// no gain.
pub trait MemorySampler: Send + Sync + 'static {
    /// Every process currently visible to this process's user.
    fn sample(&self) -> Vec<ProcessRss>;

    // Walks the table separately from `sample` rather than sharing it: see
    // `SysinfoSampler`'s own `identify` for why a shared table would give
    // stale names forever.
    /// Every process currently visible, with the name the OS reports for it.
    ///
    /// # Default implementation
    ///
    /// Empty, so a `pub` trait gains it without breaking an out-of-tree
    /// implementor. Callers must read an empty answer as "unknown", never as
    /// "no lambs".
    fn identify(&self) -> Vec<ProcessIdentity> {
        Vec::new()
    }
}

/// `MemorySampler` over sysinfo.
#[derive(Debug)]
pub struct SysinfoSampler {
    // std::sync::Mutex, not tokio's: the critical section is one synchronous
    // syscall walk, never held across an .await. Needed because `sample`
    // takes `&self`, so this can live behind a shared `Arc<dyn MemorySampler>`.
    system: Mutex<System>,
}

impl SysinfoSampler {
    /// A sampler holding an empty process table.
    ///
    /// Construction does no refresh: the first [`MemorySampler::sample`] call
    /// performs the first walk, so building one at boot cannot block.
    #[must_use]
    pub fn new() -> Self {
        Self {
            system: Mutex::new(System::new()),
        }
    }
}

// clippy's `new_without_default` fires under `-D warnings` for a `new()`
// that takes no arguments; this impl silences it.
impl Default for SysinfoSampler {
    fn default() -> Self {
        Self::new()
    }
}

/// The refresh kind [`SysinfoSampler::sample`] asks sysinfo for, named so
/// a test can assert on the flags directly.
///
/// `.with_cpu()`: without it sysinfo leaves `accumulated_cpu_time` at 0, so
/// every derived percentage reads a plausible, wrong `0.0`.
/// `.without_tasks()`: `nothing()` defaults `tasks` to on, and on Linux that
/// lists each thread as a row [`tree_rss`] cannot tell from a real child.
fn sample_refresh_kind() -> ProcessRefreshKind {
    ProcessRefreshKind::nothing()
        .with_memory()
        .with_cpu()
        .without_tasks()
}

/// The refresh kind [`SysinfoSampler::identify`] asks sysinfo for.
///
/// Neither `.with_memory()` nor `.with_cpu()`: this walk reads only `name()`
/// and `parent()`, so `shep describe` does not pay the poll's syscalls for
/// figures it does not read.
///
/// `.without_tasks()`, for the reason [`sample_refresh_kind`] gives.
fn identify_refresh_kind() -> ProcessRefreshKind {
    ProcessRefreshKind::nothing().without_tasks()
}

impl MemorySampler for SysinfoSampler {
    fn sample(&self) -> Vec<ProcessRss> {
        // Recovers from a poisoned lock rather than propagating the panic:
        // refusing every later poll over one bad reading is worse for a
        // supervisor that must stay up.
        let mut system = self.system.lock().unwrap_or_else(PoisonError::into_inner);
        // `ProcessesToUpdate::All`: refreshing only already-known pids would
        // miss a lamb the sheep forked since the last poll.
        system.refresh_processes_specifics(ProcessesToUpdate::All, true, sample_refresh_kind());
        system
            .processes()
            .values()
            .map(|process| ProcessRss {
                pid: process.pid().as_u32(),
                parent: process.parent().map(sysinfo::Pid::as_u32),
                bytes: process.memory(),
                cpu_ms: process.accumulated_cpu_time(),
            })
            .collect()
    }

    fn identify(&self) -> Vec<ProcessIdentity> {
        // Fresh `System`, not `self.system`: sysinfo fixes a process's name
        // on first sight of its pid, so the enforcer's retained table would
        // give a lamb its pre-exec wrapper-shell name forever.
        let mut system = System::new();
        system.refresh_processes_specifics(ProcessesToUpdate::All, true, identify_refresh_kind());
        system
            .processes()
            .values()
            .map(|process| ProcessIdentity {
                pid: process.pid().as_u32(),
                parent: process.parent().map(sysinfo::Pid::as_u32),
                name: process.name().to_string_lossy().into_owned(),
            })
            .collect()
    }
}

/// Shared index over one sampled `table`: a byte total, a CPU-time total and
/// a child list per pid, built once and walked as many times as needed.
///
/// Build one per table and call [`TreeIndex::sum_from`] per root when
/// summing several roots (the polling enforcer's per-tick loop): rebuilding
/// per root would multiply the per-tick cost by flock size. [`tree_rss`]
/// builds one and walks it once, the right shape for a single sum.
#[derive(Debug)]
pub(crate) struct TreeIndex {
    bytes_by_pid: HashMap<u32, u64>,
    cpu_by_pid: HashMap<u32, u64>,
    children_of: HashMap<u32, Vec<u32>>,
}

impl TreeIndex {
    /// Indexes `table`: a byte total, a CPU-time total and a child list per
    /// pid.
    pub(crate) fn build(table: &[ProcessRss]) -> Self {
        // Indexed once so a caller summing multiple roots (the polling
        // enforcer, one root per armed id) reuses this instead of rescanning
        // the whole-machine table per root.
        let mut bytes_by_pid: HashMap<u32, u64> = HashMap::with_capacity(table.len());
        let mut cpu_by_pid: HashMap<u32, u64> = HashMap::with_capacity(table.len());
        // Sized like the two maps above rather than from empty: at most one
        // key per row, and growing from nothing rehashes its way up on every
        // build, which is once a tick.
        let mut children_of: HashMap<u32, Vec<u32>> = HashMap::with_capacity(table.len());
        for entry in table {
            bytes_by_pid.insert(entry.pid, entry.bytes);
            cpu_by_pid.insert(entry.pid, entry.cpu_ms);
            if let Some(parent) = entry.parent {
                children_of.entry(parent).or_default().push(entry.pid);
            }
        }
        Self {
            bytes_by_pid,
            cpu_by_pid,
            children_of,
        }
    }

    /// Sums resident memory over `root` and every descendant this index
    /// knows about.
    ///
    /// A pid absent from the index contributes nothing; a cycle in the
    /// parent links (which the kernel does not produce but a fixture can)
    /// terminates rather than recursing forever.
    pub(crate) fn sum_from(&self, root: u32) -> u64 {
        self.total_over(root, &self.bytes_by_pid)
    }

    /// Sums accumulated CPU time over `root` and every descendant, exactly
    /// as [`Self::sum_from`] sums resident memory.
    pub(crate) fn cpu_from(&self, root: u32) -> u64 {
        self.total_over(root, &self.cpu_by_pid)
    }

    /// Every descendant of `root` this index knows about, `root` excluded.
    ///
    /// The one tree walk here, which [`Self::total_over`] sums over too.
    pub(crate) fn descendants_of(&self, root: u32) -> HashSet<u32> {
        // Seeded with `root`: a self-parenting pid or a parent-link cycle (a
        // fixture can produce one) terminates, and never re-counts `root`.
        let mut seen = HashSet::from([root]);
        let mut stack = vec![root];
        while let Some(pid) = stack.pop() {
            for &child in self.children_of.get(&pid).into_iter().flatten() {
                if seen.insert(child) {
                    stack.push(child);
                }
            }
        }
        seen.remove(&root);
        seen
    }

    /// Sums `totals` over `root` and every descendant this index knows about.
    ///
    /// Shared by both per-pid quantities, over [`Self::descendants_of`]'s walk.
    fn total_over(&self, root: u32, totals: &HashMap<u32, u64>) -> u64 {
        let reading = |pid: u32| totals.get(&pid).copied().unwrap_or(0);
        self.descendants_of(root)
            .into_iter()
            .fold(reading(root), |sum, pid| sum.saturating_add(reading(pid)))
    }
}

/// Sums resident memory over `root` and every descendant in `table`.
///
/// A pid absent from `table` contributes nothing; a cycle in the parent
/// links terminates rather than recursing forever.
///
/// Builds a fresh `TreeIndex` every call: use `TreeIndex` directly to
/// sum several roots out of the same table.
#[must_use]
pub fn tree_rss(table: &[ProcessRss], root: u32) -> u64 {
    TreeIndex::build(table).sum_from(root)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::testing::{rss, rss_cpu};

    #[test]
    fn lone_root_sums_its_own_bytes() {
        let table = [rss(1, None, 100)];
        assert_eq!(tree_rss(&table, 1), 100);
    }

    #[test]
    fn descendants_reach_every_generation_and_leave_out_a_root_a_cycle_leads_back_to() {
        let index = TreeIndex::build(&[
            rss(1, None, 0),
            rss(2, Some(1), 0),
            rss(3, Some(2), 0),
            rss(4, None, 0),
            rss(1, Some(3), 0),
        ]);
        assert_eq!(index.descendants_of(1), HashSet::from([2, 3]));
        assert!(index.descendants_of(99).is_empty());
    }

    #[test]
    fn root_with_two_children_sums_all_three() {
        let table = [rss(1, None, 100), rss(2, Some(1), 20), rss(3, Some(1), 30)];
        assert_eq!(tree_rss(&table, 1), 150);
    }

    #[test]
    fn three_deep_chain_sums_every_generation() {
        let table = [rss(1, None, 100), rss(2, Some(1), 20), rss(3, Some(2), 5)];
        assert_eq!(tree_rss(&table, 1), 125);
    }

    // Distinguishes the two likely wrong sums (1029, 1329) from the correct 230.
    #[test]
    fn sibling_subtree_is_excluded() {
        let table = [
            rss(1, None, 100),    // an unrelated root, not an ancestor of pid 2
            rss(2, None, 200),    // the root this call actually asks about
            rss(3, Some(2), 30),  // pid 2's own child, counted
            rss(4, Some(1), 999), // under the sibling, must not be counted
        ];
        assert_eq!(tree_rss(&table, 2), 230);
    }

    #[test]
    fn root_absent_from_table_sums_to_zero() {
        let table = [rss(1, None, 100)];
        assert_eq!(tree_rss(&table, 999), 0);
    }

    #[test]
    fn cpu_sums_the_whole_tree_including_the_root() {
        let table = [
            rss_cpu(100, None, 1024, 500),
            rss_cpu(101, Some(100), 2048, 250),
            rss_cpu(102, Some(101), 4096, 125),
        ];
        let index = TreeIndex::build(&table);
        assert_eq!(index.cpu_from(100), 875);
        assert_eq!(index.cpu_from(101), 375);
        assert_eq!(index.sum_from(100), 7168, "memory must be unaffected");
    }

    #[test]
    fn self_parenting_pid_terminates_and_counts_once() {
        let table = [rss(1, Some(1), 100)];
        assert_eq!(tree_rss(&table, 1), 100);
    }

    #[test]
    fn two_cycle_terminates_and_counts_each_once() {
        let table = [rss(2, Some(3), 40), rss(3, Some(2), 60)];
        assert_eq!(tree_rss(&table, 2), 100);
    }

    #[test]
    fn memory_sampler_is_dyn_compatible() {
        let _: &dyn MemorySampler = &SysinfoSampler::new();
    }

    const _: fn() = || {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<SysinfoSampler>();
    };

    // Asserts only wiring (refresh flags, Pid->u32, field mapping): an exact
    // byte count would test sysinfo, not us. The parent pid is checked on
    // unix against `parent_id`, which the sampler does not read.
    #[test]
    fn sysinfo_sampler_finds_this_process_with_nonzero_rss() {
        let sampler = SysinfoSampler::new();
        let pid = std::process::id();
        let table = sampler.sample();
        let reading = table
            .iter()
            .copied()
            .find(|p| p.pid == pid)
            .unwrap_or_else(|| panic!("own pid {pid} not found in sampled process table"));
        assert!(reading.bytes > 0, "own RSS reading was zero");

        // Whole-table, not own-pid: a fresh test binary can honestly read
        // zero CPU-milliseconds, so this checks the table has any nonzero
        // entry instead.
        assert!(
            table.iter().any(|p| p.cpu_ms > 0),
            "no entry in the table carried any accumulated CPU time; \
             the refresh is missing `.with_cpu()`"
        );

        // Guards parent-pid wiring: a sampler that hardcoded `parent: None`
        // or refreshed only the own pid would still pass the RSS assertion
        // above while collapsing the tree to the root.
        assert!(table.len() > 1, "table had only one process in it");
        assert!(
            table.iter().any(|p| p.parent.is_some()),
            "no entry in the table carried a parent pid"
        );
        let parent = reading
            .parent
            .unwrap_or_else(|| panic!("own reading for pid {pid} carried no parent"));
        #[cfg(unix)]
        assert_eq!(
            reading.parent,
            Some(std::os::unix::process::parent_id()),
            "sampler reported a parent other than the one the OS gives this process"
        );
        assert!(
            tree_rss(&table, parent) > reading.bytes,
            "tree sum rooted at own parent ({parent}) was not larger than this process's own RSS"
        );
    }

    #[test]
    fn scripted_sampler_replays_in_order_then_repeats_last() {
        let under = vec![rss(1, None, 100)];
        let over = vec![rss(1, None, 900)];
        let sampler = crate::testing::ScriptedSampler::new(vec![under.clone(), over.clone()]);
        assert_eq!(
            sampler.sample(),
            under,
            "call 1 should be the first reading"
        );
        assert_eq!(
            sampler.sample(),
            over,
            "call 2 should be the second reading"
        );
        assert_eq!(
            sampler.sample(),
            over,
            "call 3, past the end of the script, should repeat the last reading"
        );
    }

    #[test]
    fn scripted_sampler_calls_counts_every_invocation() {
        let sampler = crate::testing::ScriptedSampler::new(vec![vec![rss(1, None, 1)]]);
        assert_eq!(sampler.calls(), 0);
        sampler.sample();
        sampler.sample();
        sampler.sample();
        assert_eq!(sampler.calls(), 3);
    }

    // Asserts the flags directly rather than behavior: macOS ignores
    // `tasks` entirely, so a regression here would be invisible to a local
    // run and show up only on an operator's Linux box.
    #[test]
    fn the_sampling_refresh_kind_asks_for_memory_and_cpu_but_never_tasks() {
        let kind = sample_refresh_kind();
        assert!(kind.memory(), "the tree sum is a memory sum");
        assert!(
            kind.cpu(),
            "without this `accumulated_cpu_time` stays at 0 and every \
             percentage reads a plausible, wrong 0.0"
        );
        assert!(
            !kind.tasks(),
            "`tasks` makes sysinfo's Linux backend list every thread as a \
             process parented to its own process, which multiplies a sheep's \
             reported memory by its thread count"
        );
    }

    #[test]
    fn the_identify_refresh_kind_asks_for_neither_memory_nor_cpu_nor_tasks() {
        let kind = identify_refresh_kind();
        assert!(!kind.memory(), "identify reads only `name` and `parent`");
        assert!(!kind.cpu(), "identify reads only `name` and `parent`");
        assert!(
            !kind.tasks(),
            "`tasks` would make `shep describe` report every thread of a \
             sheep as one of its lambs"
        );
    }

    /// Cases that need `/proc` and a real thread of this process.
    ///
    /// Linux-only: sysinfo's Apple and Windows backends have no notion of a
    /// task row. Not slow, but a macOS `cargo test` never runs these; CI's
    /// Linux legs do.
    #[cfg(target_os = "linux")]
    mod linux {
        use std::sync::mpsc;
        use std::thread;

        use super::*;

        /// Every thread id this process currently has, straight out of
        /// `/proc/self/task/`, this thread's own included.
        fn own_thread_ids() -> Vec<u32> {
            std::fs::read_dir("/proc/self/task")
                .expect("/proc/self/task exists on every Linux this daemon runs on")
                .filter_map(|entry| {
                    entry
                        .ok()?
                        .file_name()
                        .to_str()
                        .and_then(|name| name.parse::<u32>().ok())
                })
                .collect()
        }

        /// Runs `body` with `count` extra threads of this process alive and
        /// parked, so `/proc/self/task/` holds more than one entry while the
        /// sampler walks.
        ///
        /// Each thread reports in before `body` starts, since a spawn that
        /// has not reached its first instruction has no task directory yet.
        /// They park on a `recv` that returns only when their sender drops.
        fn with_extra_threads<T>(count: usize, body: impl FnOnce() -> T) -> T {
            let (report_started, started) = mpsc::channel::<()>();
            let mut releases = Vec::with_capacity(count);
            let mut handles = Vec::with_capacity(count);
            for _ in 0..count {
                let (release, parked) = mpsc::channel::<()>();
                let report_started = report_started.clone();
                releases.push(release);
                handles.push(thread::spawn(move || {
                    report_started
                        .send(())
                        .expect("the test thread outlives every thread it parks");
                    // Returns `Err` when `releases` drops below; either way
                    // this thread is done.
                    let _ = parked.recv();
                }));
            }
            drop(report_started);
            for _ in 0..count {
                started
                    .recv()
                    .expect("every parked thread reports in before it parks");
            }

            let out = body();

            drop(releases);
            for handle in handles {
                handle.join().expect("a parked thread cannot panic");
            }
            out
        }

        // A thread row would be parented like a real child, and its
        // /proc/<pid>/task/<tid>/statm reports the whole process's RSS, so
        // a leaked row multiplies the sheep's reported memory.
        #[test]
        fn the_sample_table_holds_no_thread_of_this_process() {
            let own_pid = std::process::id();
            with_extra_threads(4, || {
                let threads: Vec<u32> = own_thread_ids()
                    .into_iter()
                    .filter(|tid| *tid != own_pid)
                    .collect();
                assert!(
                    !threads.is_empty(),
                    "the case says nothing unless this process really has \
                     threads other than its main one; it did not"
                );

                let table = SysinfoSampler::new().sample();
                let sampled: HashSet<u32> = table.iter().map(|entry| entry.pid).collect();
                let leaked: Vec<u32> = threads
                    .into_iter()
                    .filter(|tid| sampled.contains(tid))
                    .collect();

                assert!(
                    sampled.contains(&own_pid),
                    "the walk has to see this process at all, or a clean \
                     result below means only that the walk failed"
                );
                assert!(
                    leaked.is_empty(),
                    "the table must hold processes, not threads; these \
                     thread ids of pid {own_pid} were sampled as processes \
                     in their own right: {leaked:?}"
                );
            });
        }

        // A leaked thread row here would make `stats`' lamb index list it
        // as a lamb in `shep describe`.
        #[test]
        fn identify_reports_no_thread_of_this_process() {
            let own_pid = std::process::id();
            with_extra_threads(4, || {
                let threads: Vec<u32> = own_thread_ids()
                    .into_iter()
                    .filter(|tid| *tid != own_pid)
                    .collect();
                assert!(
                    !threads.is_empty(),
                    "the case says nothing unless this process really has \
                     threads other than its main one; it did not"
                );

                let identified: HashSet<u32> = SysinfoSampler::new()
                    .identify()
                    .into_iter()
                    .map(|identity| identity.pid)
                    .collect();
                let leaked: Vec<u32> = threads
                    .into_iter()
                    .filter(|tid| identified.contains(tid))
                    .collect();

                assert!(
                    identified.contains(&own_pid),
                    "the walk has to see this process at all, or a clean \
                     result below means only that the walk failed"
                );
                assert!(
                    leaked.is_empty(),
                    "a lamb is a child process, never a thread; these thread \
                     ids of pid {own_pid} were identified as processes: \
                     {leaked:?}"
                );
            });
        }
    }

    /// Tests that spawn a real process and wait on real elapsed time.
    ///
    /// Skipped by `--skip ::slow::`; nothing here is `#[ignore]`d.
    mod slow {
        // Read only by the cfg(unix) cases below. No Windows twin here;
        // tests/real_runner_windows.rs covers real-child behavior at the
        // runner tier instead.
        #[cfg(unix)]
        use std::process::{Command, Stdio};
        #[cfg(unix)]
        use std::time::{Duration, Instant};

        #[cfg(unix)]
        use super::*;

        /// How long [`name_when`] keeps walking before giving up and
        /// reporting whatever it last saw.
        ///
        /// 10s = 10,000ms, against 5.7ms to 12.0ms for one `identify` walk
        /// over 787 processes on an idle arm64 macOS host, so roughly a
        /// thousand walks' worth. Margin against a stalled runner rather
        /// than an estimate of the work.
        #[cfg(unix)]
        const GIVE_UP_AFTER: Duration = Duration::from_secs(10);

        /// The gap between walks in [`name_when`].
        ///
        /// 10ms is about what the walk it follows costs, 5.7ms to 12.0ms
        /// measured as above, so the loop alternates walking and waiting
        /// instead of spinning on the process table.
        #[cfg(unix)]
        const BETWEEN_WALKS: Duration = Duration::from_millis(10);

        /// The name `sampler` reports for `pid`, or `None` if the walk did
        /// not see it.
        ///
        /// `cfg(unix)` alongside its only caller, below.
        #[cfg(unix)]
        fn name_of(sampler: &SysinfoSampler, pid: u32) -> Option<String> {
            sampler
                .identify()
                .into_iter()
                .find(|identity| identity.pid == pid)
                .map(|identity| identity.name)
        }

        /// Walks until `accept` is happy with the name `pid` is reported
        /// under, then returns that name.
        ///
        /// Returns the last name seen once [`GIVE_UP_AFTER`] elapses, so a
        /// caller whose `accept` never fired asserts against a real
        /// observation rather than against having run out of patience.
        /// `cfg(unix)` alongside its only callers, below.
        #[cfg(unix)]
        fn name_when(
            sampler: &SysinfoSampler,
            pid: u32,
            accept: impl Fn(Option<&str>) -> bool,
        ) -> Option<String> {
            let deadline = Instant::now() + GIVE_UP_AFTER;
            loop {
                let seen = name_of(sampler, pid);
                if accept(seen.as_deref()) || Instant::now() >= deadline {
                    return seen;
                }
                std::thread::sleep(BETWEEN_WALKS);
            }
        }

        // Pins `identify` reading the post-exec name, not a stale one from
        // a retained table. unix only: Windows has no fork-then-exec
        // equivalent, and spawning a real process is why this lives in
        // `slow`.
        #[cfg(unix)]
        #[test]
        fn identify_reports_the_name_a_lamb_execed_into_not_the_one_it_forked_with() {
            let mut child = Command::new("/bin/sh")
                .arg("-c")
                // `read` rather than a `sleep` long enough to win the race:
                // the child blocks here until this end of the pipe closes, so
                // the walk below cannot arrive after the `exec` however slow
                // the machine is. The `read` ends on EOF as readily as on a line.
                .arg("read _; exec sleep 30")
                .stdin(Stdio::piped())
                .spawn()
                .expect("/bin/sh is present on every platform this daemon supports");
            let pid = child.id();
            let sampler = SysinfoSampler::new();

            // Any name but `sleep`, rather than the shell's own name: this
            // case pins that the second walk is fresh, and which shell the
            // first walk caught is not its business. macOS `/bin/sh` is a
            // shim that execs `/bin/bash`, so pinning `sh` pinned a sub-millisecond window.
            let forked_as = name_when(&sampler, pid, |name| name.is_some());
            // Releases the child into its `exec`. Before the assertions, so
            // a failing one cannot leave a shell blocked on `read` forever.
            drop(child.stdin.take());
            let execed_into = name_when(&sampler, pid, |name| name == Some("sleep"));

            let _ = child.kill();
            let _ = child.wait();

            assert!(
                forked_as.is_some(),
                "the first walk has to see pid {pid} at all, or the case says \
                 nothing about what a later walk reports for it"
            );
            assert_ne!(
                forked_as.as_deref(),
                Some("sleep"),
                "pid {pid} was still blocked on `read` here, so no walk could \
                 yet have seen the `exec`; this one did"
            );
            assert_eq!(
                execed_into.as_deref(),
                Some("sleep"),
                "the second walk must report what pid {pid} is NOW, not what \
                 the first walk recorded for it"
            );
        }
    }
}