detcore/syscalls/

threads.rs

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree.
 */

//! System calls for dealing with threads and concurrency.

use std::collections::HashMap;
use std::marker::PhantomData;
use std::sync::Arc;
use std::sync::Mutex;
use std::time::Duration;

use procfs::process::Process;
use rand::Rng;
use reverie::BackendCapabilities;
use reverie::Error;
use reverie::GlobalRPC;
use reverie::Guest;
use reverie::Pid;
use reverie::Stack;
use reverie::syscalls;
use reverie::syscalls::Addr;
use reverie::syscalls::AddrMut;
use reverie::syscalls::CloneFlags;
use reverie::syscalls::Errno;
use reverie::syscalls::MemoryAccess;
use reverie::syscalls::ReadAddr;
use reverie::syscalls::Syscall;
use reverie::syscalls::SyscallInfo;
use reverie::syscalls::Timespec;
use reverie::syscalls::WaitPidFlag;
use tracing::debug;
use tracing::error;
use tracing::info;
use tracing::trace;

use crate::SharedMemoryObjectId;
use crate::config::BlockingMode;
use crate::config::Config;
use crate::config::SchedHeuristic;
use crate::memory::MemoryMetadata;
use crate::record_or_replay::RecordOrReplay;
use crate::resources::ExternalOpId;
use crate::resources::Permission;
use crate::resources::ResourceID;
use crate::resources::Resources;
use crate::scheduler::FutexSignalWatch;
use crate::scheduler::HostTimedSignalScope;
use crate::scheduler::SchedValue;
use crate::scheduler::pid_namespaces::GuestPidAnswer;
use crate::syscalls::guest_siginfo::GuestSiginfo;
use crate::syscalls::helpers::NonblockableSyscall;
use crate::syscalls::helpers::RestartCall;
use crate::syscalls::helpers::keep_restart_block;
use crate::syscalls::helpers::record_retry_event;
use crate::syscalls::helpers::retry_nonblocking_syscall;
use crate::syscalls::helpers::retry_nonblocking_syscall_with_timeout;
use crate::syscalls::pi_futex;
use crate::syscalls::pi_futex::LockPiStep;
use crate::syscalls::pi_futex::PiFutexState;
use crate::syscalls::pi_futex::PiHandOver;
use crate::syscalls::pi_futex::UnlockPiStep;
use crate::syscalls::robust_list;
use crate::tool_global::FutexAction;
use crate::tool_global::GlobalState;
use crate::tool_global::ResumeStatus;
use crate::tool_global::await_exact_child_physical_exit;
use crate::tool_global::cancel_exec;
use crate::tool_global::child_tid_clear_address;
use crate::tool_global::consume_child_wait;
use crate::tool_global::create_child_thread;
use crate::tool_global::futex_action;
use crate::tool_global::hold_turn_for_group_exit;
use crate::tool_global::host_timed_signals;
use crate::tool_global::prepare_exec;
use crate::tool_global::process_group;
use crate::tool_global::ready_child_wait;
use crate::tool_global::record_host_timed_signals;
use crate::tool_global::resource_request;
use crate::tool_global::set_child_tid_address;
use crate::tool_global::thread_is_live;
use crate::tool_global::thread_observe_time;
use crate::tool_global::wait_for_child_lifecycle;
use crate::tool_global::yield_once;
use crate::tool_local::Detcore;
use crate::tool_local::PendingVfork;
use crate::tool_local::RobustListExit;
use crate::tool_local::RobustListOwner;
use crate::tool_local::RobustListWake;
use crate::tool_local::ThreadState;
use crate::types::ChildWaitExitClass;
use crate::types::ChildWaitSelector;
use crate::types::ChildWaitSpec;
use crate::types::DetPid;
use crate::types::DetTid;
use crate::types::ExactChildWaitState;
use crate::types::FutexID;
use crate::types::LogicalTime;
use crate::types::SigWrapper;

#[path = "affinity.rs"]
mod affinity;
#[path = "emulated_waitid.rs"]
mod emulated_waitid;

// Preserve the historical Detcore ABI while hiding the host's configured CPU
// count. This represents one virtual CPU in a fixed 128-bit kernel mask.
pub(crate) const VIRTUAL_CPUSET_BYTES: usize = 16;

const IOPRIO_WHO_PROCESS: libc::c_int = 1;
const IOPRIO_WHO_PGRP: libc::c_int = 2;
const IOPRIO_WHO_USER: libc::c_int = 3;
const IOPRIO_CLASS_SHIFT: libc::c_int = 13;
const IOPRIO_CLASS_BE: libc::c_int = 2;
const IOPRIO_BE_NORM: libc::c_int = 4;
const IOPRIO_DEFAULT_EFFECTIVE: libc::c_int =
    (IOPRIO_CLASS_BE << IOPRIO_CLASS_SHIFT) | IOPRIO_BE_NORM;

// sched_attr wire contract, from include/uapi/linux/sched/types.h. These are
// spelled out rather than derived from `size_of::<libc::sched_attr>()`: the
// value the kernel reports back on the E2BIG paths and the offset past which
// trailing bytes must be zero are properties of the KERNEL's struct, which is
// larger than the libc crate's 48-byte mirror. Deriving either from a Rust type
// would silently re-point the contract if that type ever grows a field.
const SCHED_ATTR_SIZE_VER0: u32 = 48; // first published struct
const SCHED_ATTR_SIZE_VER1: u32 = 56; // adds sched_util_{min,max}
/// The kernel's own `sizeof(struct sched_attr)`. Two things key off it: bytes at
/// or beyond this offset must be zero, and it is the value written back into
/// `uattr->size` when the request is refused with E2BIG.
const SCHED_ATTR_KERNEL_SIZE: u32 = SCHED_ATTR_SIZE_VER1;
/// `sched_copy_attr` and `sched_getattr` refuse a buffer larger than one page
/// (kernel/sched/syscalls.c).
fn sched_attr_max_size() -> u32 {
    u32::try_from(crate::page::page_size()).expect("the page size fits in u32")
}

/// The scheduling policy Detcore presents as every thread's current one.
///
/// This is not a guess about the host. It is the value `handle_sched_getattr`
/// writes back for every thread, so it is the policy a guest observes and the
/// only policy `SCHED_FLAG_KEEP_POLICY` can be keeping.
const VIRTUAL_CURRENT_POLICY: u32 = libc::SCHED_OTHER as u32;

/// Outcome of scanning the bytes past the kernel's `struct sched_attr`.
#[derive(Debug, Eq, PartialEq)]
enum TailVerdict {
    AllZero,
    /// A byte the kernel does not understand was set: `copy_struct_from_user`
    /// reports this as E2BIG, after storing its own size back.
    NotZeroed,
    /// Guest memory could not be read before any non-zero byte was seen.
    Faulted,
}

/// Reads of eight bytes or fewer take safeptrace's `PTRACE_PEEKDATA` path,
/// which reads a whole aligned word and BYPASSES GUEST PAGE PROTECTIONS. Only a
/// read strictly larger than that reaches `process_vm_readv`, which honours
/// them. Note this is not symmetric with the write side: `write` special-cases
/// a length of exactly eight, so splitting a write in half escapes it, while
/// `read` special-cases eight *or fewer* and splitting only makes it worse.
const MIN_PROTECTION_RESPECTING_READ: usize = std::mem::size_of::<u64>() + 1;

/// Scan `tail_len` bytes at `base + tail_off` the way `check_zeroed_user` does.
///
/// Two things here are load-bearing and neither is visible from the outcome
/// alone, only from the ORDER the outcome is reached in.
///
/// First, Linux scans FORWARD and stops at the first thing it finds. A non-zero
/// byte followed later by an unreadable page is E2BIG, because the scan never
/// reaches the page; an unreadable page reached before any non-zero byte is
/// EFAULT. Reading the whole tail up front and judging afterwards collapses
/// both into EFAULT and silently changes the errno a guest sees.
///
/// Second, every read here is kept strictly larger than eight bytes, for the
/// reason on [`MIN_PROTECTION_RESPECTING_READ`]. Where the remainder is
/// smaller, the window is extended BACKWARDS over bytes already scanned rather
/// than shortened; re-reading a byte is free and only the new bytes are judged.
fn scan_tail_is_zeroed<M: MemoryAccess>(
    memory: &M,
    base: AddrMut<u8>,
    tail_off: usize,
    tail_len: usize,
) -> TailVerdict {
    const CHUNK: usize = 256;
    let mut done = 0usize;
    let mut buf = [0u8; CHUNK];
    while done < tail_len {
        let remaining = tail_len - done;
        let want = remaining.min(CHUNK);
        // Extend backwards when the remainder alone would be a small read.
        // The window may reach back past the start of the tail into the
        // `sched_attr` prefix: the kernel has already read those bytes, so they
        // are readable, and only the new bytes are judged below. Clamping this
        // to `done` alone left a 1-byte tail with nowhere to grow into and
        // issued exactly the small read this constant exists to avoid.
        let back = MIN_PROTECTION_RESPECTING_READ
            .saturating_sub(want)
            .min(done + tail_off);
        let read_len = want + back;
        let start = tail_off + done - back;
        let Some(addr) = base
            .as_raw()
            .checked_add(start)
            .and_then(AddrMut::<u8>::from_raw)
        else {
            return TailVerdict::Faulted;
        };
        // A failed read means zero NEW bytes were obtained; the `got < read_len`
        // check below is what turns that into `Faulted`. Written `unwrap_or(0)`
        // rather than `unwrap_or_default()` so the 0 stays visible.
        let got = memory.read(addr, &mut buf[..read_len]).unwrap_or(0);
        // Judge only the bytes that are genuinely new AND genuinely read.
        let new_from = back.min(got);
        if buf[new_from..got].iter().any(|byte| *byte != 0) {
            return TailVerdict::NotZeroed;
        }
        if got < read_len {
            // The scan stopped at an unreadable byte with nothing non-zero
            // before it, which is `check_zeroed_user`'s -EFAULT.
            return TailVerdict::Faulted;
        }
        done += want;
    }
    TailVerdict::AllZero
}

// Scheduling policies, from include/uapi/linux/sched.h.
const SCHED_FIFO: u32 = 1;
const SCHED_RR: u32 = 2;
const SCHED_DEADLINE: u32 = 6;
const SCHED_EXT: u32 = 7;
/// The kernel's `MAX_RT_PRIO`; valid real-time priorities are 1..=99.
const MAX_RT_PRIO: u32 = 100;

// Byte offsets of the fields this handler inspects. Taken from the UAPI struct
// rather than from a Rust mirror, for the reason given above.
const SCHED_ATTR_OFF_POLICY: usize = 4;
const SCHED_ATTR_OFF_FLAGS: usize = 8;
const SCHED_ATTR_OFF_PRIORITY: usize = 20;
const SCHED_ATTR_OFF_RUNTIME: usize = 24;
const SCHED_ATTR_OFF_DEADLINE: usize = 32;
const SCHED_ATTR_OFF_PERIOD: usize = 40;

// sched_attr.sched_flags bits, from include/uapi/linux/sched.h.
const SCHED_FLAG_RESET_ON_FORK: u64 = 0x01;
const SCHED_FLAG_RECLAIM: u64 = 0x02;
const SCHED_FLAG_DL_OVERRUN: u64 = 0x04;
const SCHED_FLAG_KEEP_POLICY: u64 = 0x08;
const SCHED_FLAG_KEEP_PARAMS: u64 = 0x10;
const SCHED_FLAG_UTIL_CLAMP_MIN: u64 = 0x20;
const SCHED_FLAG_UTIL_CLAMP_MAX: u64 = 0x40;
const SCHED_FLAG_UTIL_CLAMP: u64 = SCHED_FLAG_UTIL_CLAMP_MIN | SCHED_FLAG_UTIL_CLAMP_MAX;
const SCHED_FLAG_ALL: u64 = SCHED_FLAG_RESET_ON_FORK
    | SCHED_FLAG_RECLAIM
    | SCHED_FLAG_DL_OVERRUN
    | SCHED_FLAG_KEEP_POLICY
    | SCHED_FLAG_KEEP_PARAMS
    | SCHED_FLAG_UTIL_CLAMP;

/// Whether Linux accepts `policy` as a scheduling policy for `sched_setattr`.
/// This is the kernel's `valid_policy()`: idle, fair, rt, deadline or ext. Note
/// the gap at 4 -- SCHED_ISO is reserved and never valid -- and that 7 is
/// SCHED_EXT, which `valid_policy()` accepts on a kernel built with
/// CONFIG_SCHED_CLASS_EXT.
fn is_valid_sched_policy(policy: u32) -> bool {
    matches!(
        policy,
        // SCHED_OTHER/NORMAL, FIFO, RR, BATCH
        0 | 1 | 2 | 3
        // SCHED_IDLE
        | 5
        | SCHED_DEADLINE
        | SCHED_EXT
    )
}

/// The kernel's `rt_policy()`: the two fixed-priority real-time policies.
fn is_rt_policy(policy: u32) -> bool {
    policy == SCHED_FIFO || policy == SCHED_RR
}

/// The kernel's `__checkparam_dl()`, restricted to the parts that are pure ABI.
///
/// The kernel's final test compares the period against
/// `sysctl_sched_dl_period_{min,max}`, which are runtime-tunable. That bound is
/// a property of the host's configuration rather than of the interface, so it
/// is deliberately not reproduced here -- see the handler's doc comment for the
/// other cases in that class.
fn deadline_params_are_valid(runtime: u64, deadline: u64, period: u64) -> bool {
    // deadline != 0
    if deadline == 0 {
        return false;
    }
    // The kernel truncates DL_SCALE (10) bits, so runtime must be at least that
    // big to survive the truncation.
    if runtime < (1u64 << 10) {
        return false;
    }
    // The MSB is reserved for wrap-around and sign handling.
    if deadline & (1u64 << 63) != 0 || period & (1u64 << 63) != 0 {
        return false;
    }
    // A zero period means "same as the deadline".
    let period = if period == 0 { deadline } else { period };
    // runtime <= deadline <= period
    runtime <= deadline && deadline <= period
}

/// Apply `sched_copy_attr`'s size rules to the `size` the guest declared.
///
/// `Ok(n)` is the effective size to copy with; `Err(())` means the request is
/// refused with E2BIG *and* the kernel first writes its own struct size back
/// into `uattr->size`, so the caller owes that store.
///
/// The zero case is not a mistake: the kernel carries an explicit ABI
/// compatibility quirk, `if (!size) size = SCHED_ATTR_SIZE_VER0;`, so a
/// zero-sized request is a well-formed VER0 request and succeeds.
fn sched_attr_effective_size(declared: u32) -> Result<u32, ()> {
    let size = if declared == 0 {
        SCHED_ATTR_SIZE_VER0
    } else {
        declared
    };
    if !(SCHED_ATTR_SIZE_VER0..=sched_attr_max_size()).contains(&size) {
        return Err(());
    }
    Ok(size)
}

/// The descriptor fields this handler inspects, decoded from the guest's bytes.
#[derive(Clone, Copy, Debug)]
struct SchedAttrFields {
    policy: u32,
    sched_flags: u64,
    priority: u32,
    runtime: u64,
    deadline: u64,
    period: u64,
}

/// The checks that run in `sched_copy_attr` and in the `sched_setattr` wrapper,
/// i.e. everything the kernel decides *before* it looks the target pid up.
///
/// `size` is the effective size from [`sched_attr_effective_size`], so the
/// util-clamp rule can be stated in the same terms the kernel uses.
///
/// Measured: with a pid that does not exist, both of these still report their
/// own errno rather than ESRCH, which is what places them on this side of the
/// lookup.
fn validate_sched_attr_before_lookup(size: u32, attr: &SchedAttrFields) -> Result<(), Errno> {
    // `sched_copy_attr`: util-clamp lives past the VER0 tail, so asking for it
    // with a VER0 buffer is incoherent.
    if attr.sched_flags & SCHED_FLAG_UTIL_CLAMP != 0 && size < SCHED_ATTR_SIZE_VER1 {
        return Err(Errno::EINVAL);
    }
    // `sched_setattr`: the policy is compared as a *signed* int, and this test
    // sits above the KEEP_POLICY substitution below, so the sign bit is refused
    // even when the policy field is otherwise ignored.
    if (attr.policy as i32) < 0 {
        return Err(Errno::EINVAL);
    }
    Ok(())
}

/// The checks inside `__sched_setscheduler`, i.e. everything the kernel decides
/// *after* it has resolved the target pid.
///
/// Measured: with a pid that does not exist, every rule here reports ESRCH
/// instead, which is what places them on this side of the lookup.
fn validate_sched_attr_after_lookup(attr: &SchedAttrFields) -> Result<(), Errno> {
    // `sched_setattr` rewrites the policy to SETPARAM_POLICY (-1) when
    // KEEP_POLICY is set, and `__sched_setscheduler` then takes its
    // `policy < 0` branch. That branch does not skip the policy-dependent
    // rules -- it REUSES THE TASK'S CURRENT POLICY and applies them against
    // that. `valid_policy()` is the only thing it skips, which is why an
    // undefined value in the ignored field still passes.
    //
    // Detcore's current policy is not unknown: `handle_sched_getattr` reports
    // SCHED_OTHER, nice 0, priority 0 for every thread, unconditionally, and
    // that is the whole of the guest-visible scheduling state this sandbox
    // exposes. So KEEP_POLICY substitutes SCHED_OTHER here. Treating it as
    // "no policy" and skipping the rules accepted, for instance,
    // KEEP_POLICY with sched_priority=1, which Linux refuses because a
    // non-real-time current policy requires priority 0.
    //
    // These two sites must stay in step: if `handle_sched_getattr` ever
    // reports a different virtual policy, this substitution follows it.
    let policy = if attr.sched_flags & SCHED_FLAG_KEEP_POLICY != 0 {
        Some(VIRTUAL_CURRENT_POLICY)
    } else {
        if !is_valid_sched_policy(attr.policy) {
            return Err(Errno::EINVAL);
        }
        Some(attr.policy)
    };
    // No undefined sched_flags bits.
    if attr.sched_flags & !SCHED_FLAG_ALL != 0 {
        return Err(Errno::EINVAL);
    }
    // Valid priorities are 1..=MAX_RT_PRIO-1 for the real-time policies and
    // exactly 0 for every other policy, so the priority and the policy have to
    // agree; the kernel states that as `rt_policy(policy) != (prio != 0)`.
    if attr.priority > MAX_RT_PRIO - 1 {
        return Err(Errno::EINVAL);
    }
    if let Some(policy) = policy {
        if is_rt_policy(policy) != (attr.priority != 0) {
            return Err(Errno::EINVAL);
        }
        if policy == SCHED_DEADLINE
            && !deadline_params_are_valid(attr.runtime, attr.deadline, attr.period)
        {
            return Err(Errno::EINVAL);
        }
    }
    Ok(())
}

// AUTONOMOUS-BOT-IMPLEMENTED
// TODO-HUMAN-REVIEW(PR-881)
fn virtual_ioprio(which: libc::c_int) -> Result<i64, Errno> {
    match which {
        IOPRIO_WHO_PROCESS => Ok(0),
        IOPRIO_WHO_PGRP | IOPRIO_WHO_USER => Ok(i64::from(IOPRIO_DEFAULT_EFFECTIVE)),
        _ => Err(Errno::EINVAL),
    }
}

#[repr(C)]
#[derive(Clone, Copy)]
struct WaitidSigchldFields {
    pid: libc::pid_t,
    uid: libc::uid_t,
    status: libc::c_int,
    utime: libc::c_long,
    stime: libc::c_long,
}

#[repr(C)]
union WaitidSiginfoFields {
    _alignment: *mut libc::c_void,
    sigchld: WaitidSigchldFields,
}

#[repr(C)]
struct WaitidSiginfoHead {
    _base: [libc::c_int; 3],
    fields: WaitidSiginfoFields,
}

fn wait_status_is_termination(status: libc::c_int) -> bool {
    libc::WIFEXITED(status) || libc::WIFSIGNALED(status)
}

fn waitid_code_is_termination(code: libc::c_int) -> bool {
    matches!(code, libc::CLD_EXITED | libc::CLD_KILLED | libc::CLD_DUMPED)
}

fn canonicalize_waitid_siginfo(info: &mut libc::siginfo_t) {
    debug_assert!(
        std::mem::size_of::<WaitidSiginfoHead>() <= std::mem::size_of::<libc::siginfo_t>()
    );
    // SAFETY: Linux siginfo_t starts with three c_int fields followed by a
    // pointer-aligned union. Its SIGCHLD member is pid, uid, status, utime,
    // and stime in that order. The local repr(C) mirror changes only the two
    // host CPU-accounting fields and preserves the kernel-populated event.
    let sigchld = unsafe {
        &mut (*(info as *mut libc::siginfo_t).cast::<WaitidSiginfoHead>())
            .fields
            .sigchld
    };
    sigchld.utime = 0;
    sigchld.stime = 0;
}

/// `child` is the task `info_value.si_pid` names (`Detcore::task_of_guest_pid`).
fn finish_waitid_result<T, G>(
    guest: &mut G,
    call: syscalls::Waitid,
    value: i64,
    mut info_value: libc::siginfo_t,
    child: DetPid,
) -> Result<i64, Error>
where
    T: RecordOrReplay,
    G: Guest<Detcore<T>>,
{
    // SAFETY: waitid writes either zeroed output or the SIGCHLD siginfo_t
    // variant, for which libc exposes si_pid.
    let child_pid = unsafe { info_value.si_pid() };
    if child_pid != 0 {
        canonicalize_waitid_siginfo(&mut info_value);
        guest.memory().write_value(
            call.info().expect("waitid infop checked before execution"),
            &info_value,
        )?;
        if call.options() & libc::WNOWAIT == 0 && waitid_code_is_termination(info_value.si_code) {
            guest.thread_state_mut().reap_child_process_cpu_time(child);
        }
        if let Some(rusage) = call.rusage() {
            // Host CPU and scheduling counters are not deterministic.
            let usage: libc::rusage = unsafe { std::mem::zeroed() };
            guest.memory().write_value(rusage, &usage)?;
        }
    }
    Ok(value)
}

#[derive(Debug, Eq, PartialEq)]
enum ExactWaitPollDecision {
    ChildReady,
    AwaitPhysicalExit,
    ReapAfterLogicalExit,
    Interrupted,
    Retry,
}

fn exact_wait_poll_decision(
    child_ready: bool,
    signaled: bool,
    lifecycle: Option<ExactChildWaitState>,
) -> ExactWaitPollDecision {
    if child_ready {
        ExactWaitPollDecision::ChildReady
    } else if lifecycle == Some(ExactChildWaitState::PhysicalExitPending) {
        ExactWaitPollDecision::AwaitPhysicalExit
    } else if matches!(
        lifecycle,
        Some(ExactChildWaitState::LogicallyExited | ExactChildWaitState::PhysicallyExited)
    ) {
        ExactWaitPollDecision::ReapAfterLogicalExit
    } else if signaled {
        ExactWaitPollDecision::Interrupted
    } else {
        ExactWaitPollDecision::Retry
    }
}

fn stale_any_wait_must_interrupt(signaled: bool, next_ready: Option<DetPid>) -> bool {
    signaled && next_ready.is_none()
}

fn terminal_child_wait_spec(
    selector: ChildWaitSelector,
    caller: DetTid,
    options: libc::c_int,
) -> ChildWaitSpec {
    let exit_class = if options & libc::__WALL != 0 {
        ChildWaitExitClass::Any
    } else if options & libc::__WCLONE != 0 {
        ChildWaitExitClass::Clone
    } else {
        ChildWaitExitClass::Sigchld
    };
    ChildWaitSpec {
        selector,
        owner: (options & libc::__WNOTHREAD != 0).then_some(caller),
        exit_class,
    }
}

fn validate_wait4_arguments(pid: libc::pid_t, options: WaitPidFlag) -> Result<(), Errno> {
    let allowed_options = WaitPidFlag::WNOHANG
        | WaitPidFlag::WUNTRACED
        | WaitPidFlag::WCONTINUED
        | WaitPidFlag::__WNOTHREAD
        | WaitPidFlag::__WCLONE
        | WaitPidFlag::__WALL;

    // Linux kernel/exit.c:kernel_wait4 rejects unknown option bits before it
    // interprets the pid selector.
    if options.bits() & !allowed_options.bits() != 0 {
        return Err(Errno::EINVAL);
    }
    // The same function returns ESRCH for INT_MIN before looking for children,
    // because negating that selector is not representable as a pid_t.
    if pid == libc::pid_t::MIN {
        return Err(Errno::ESRCH);
    }
    Ok(())
}

// A serial emulated child wait (today KVM) represents terminal events only, including the terminal subset
// of WUNTRACED. `__WNOTHREAD` is enforced by the logical owner filter in
// `terminal_child_wait_spec`, and exact-child completion strips it before
// the backend call. Keep unsupported and unknown low-int bits on the
// backend's prevalidation path; they must not select or consume a logical
// child.
pub(super) fn wait4_uses_terminal_selector(
    options: WaitPidFlag,
    serial_emulated_wait: bool,
) -> bool {
    if serial_emulated_wait {
        options.bits() & !(libc::WNOHANG | libc::WUNTRACED | libc::__WNOTHREAD) == 0
    } else {
        !options.intersects(
            WaitPidFlag::WUNTRACED
                | WaitPidFlag::WCONTINUED
                | WaitPidFlag::__WCLONE
                | WaitPidFlag::__WALL,
        )
    }
}

/// The one completion order a backend that emulates child waits
/// (`BackendCapabilities::emulates_child_waits`) needs for both wait4 and
/// waitid, split around the backend's exact-child call.
///
/// Backend waitability precedes the child's final owner-hook CPU prefix, so
/// the caller first waits, under its retained grant and birth-owned identity,
/// for that publication. No new scheduler turn or user-memory identity read
/// occurs.
pub(super) async fn await_selected_child_cpu_publication<G, T>(
    guest: &mut G,
    child: DetPid,
    call: &str,
) -> Result<(), Error>
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    if guest
        .thread_state()
        .wait_for_child_cpu_publication(child)
        .await
    {
        Ok(())
    } else {
        Err(Error::Tool(anyhow::anyhow!(
            "emulated {call} selected child has no owned final CPU publication"
        )))
    }
}

/// After the backend's exact-child call consumed `child` (it returned the
/// child, or EFAULT after selecting it), retire it: reap its final CPU time
/// and consume Detcore's logical wait. Shared by wait4 and waitid.
pub(super) async fn retire_selected_child<G, T>(
    guest: &mut G,
    child: DetPid,
    call: &str,
) -> Result<(), Error>
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    guest.thread_state_mut().reap_child_process_cpu_time(child);
    if consume_child_wait(guest, child).await {
        Ok(())
    } else {
        Err(Error::Tool(anyhow::anyhow!(
            "emulated {call} selected child was not logically consumed"
        )))
    }
}

pub(super) async fn complete_selected_emulated_wait4<G, T>(
    guest: &mut G,
    call: syscalls::Wait4,
    child: DetPid,
) -> Result<i64, Error>
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    await_selected_child_cpu_publication(guest, child, "wait4").await?;
    // Selection already applied `__WNOTHREAD` through the logical owner
    // filter; the backend's raw wait4 accepts only WNOHANG and WUNTRACED.
    // Keep exactly those, as the waitid exact-child completion does.
    let exact = call
        .with_pid(child.as_raw())
        .with_options(WaitPidFlag::from_bits_retain(
            call.options().bits() & (libc::WNOHANG | libc::WUNTRACED),
        ));
    let result = guest.inject(exact).await;
    match result {
        Ok(pid) if pid == i64::from(child.as_raw()) => {}
        // The supported KVM wait4 selects/consumes before either status or
        // rusage copyout. EFAULT therefore consumed this exact child too.
        Err(Errno::EFAULT) => {}
        unexpected => {
            return Err(Error::Tool(anyhow::anyhow!(
                "emulated wait4 selected-child invariant failed: {unexpected:?} for {child}"
            )));
        }
    }
    retire_selected_child(guest, child, "wait4").await?;
    result.map_err(Error::from)
}

fn child_wait_can_retry_after_stale(spec: ChildWaitSpec) -> bool {
    !matches!(spec.selector, ChildWaitSelector::Exact(_))
}

pub(super) type KernelSigset = u64;
pub(super) const KERNEL_SIGSET_SIZE: usize = std::mem::size_of::<KernelSigset>();

fn signal_is_blocked(mask: &KernelSigset, signal: SigWrapper) -> bool {
    let raw_signal = signal.raw();
    (1..=KernelSigset::BITS as i32).contains(&raw_signal)
        && mask & (1_u64 << (raw_signal as u32 - 1)) != 0
}

#[repr(C)]
#[derive(Clone, Copy)]
pub(super) struct KernelSigaction {
    pub(super) handler: u64,
    pub(super) flags: u64,
    pub(super) restorer: u64,
    pub(super) mask: KernelSigset,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(super) enum WaitSignalDisposition {
    Interrupt,
    Restart,
}

fn signal_default_disposition_does_not_interrupt_child_wait(signal: SigWrapper) -> bool {
    matches!(
        signal.raw(),
        libc::SIGCHLD | libc::SIGCONT | libc::SIGURG | libc::SIGWINCH
    )
}

/// Whether `signal`'s default action ends the process, by terminating it or
/// dumping core (signal(7)): every signal except those whose default is to be
/// ignored, to stop or to continue. SIGKILL, which no handler or callback
/// sees, is left out as well. On DBT, real-time signals do not reach
/// Detcore's signal path today (<https://github.com/rrnewton/hermit/issues/4192>).
fn signal_default_action_ends_the_process(signal: SigWrapper) -> bool {
    !matches!(
        signal.raw(),
        libc::SIGCHLD
            | libc::SIGCONT
            | libc::SIGURG
            | libc::SIGWINCH
            | libc::SIGSTOP
            | libc::SIGTSTP
            | libc::SIGTTIN
            | libc::SIGTTOU
            | libc::SIGKILL
    )
}

/// Whether a run may retire a process's other threads in the turn that
/// delivers a signal ending the process (`Scheduler::commit_fatal_delivery`):
/// its threads are serialized, the kernel's signal state is the guest's own,
/// from which the delivering thread reads that the kernel carries the default
/// action out, and no gdbserver is attached, whose client decides the signal
/// when it resumes the thread.
pub(crate) fn retires_others_at_fatal_delivery(cfg: &Config) -> bool {
    cfg.sequentialize_threads && cfg.backend.kernel_signal_state_is_guests && !cfg.gdbserver
}

/// Whether delivering `signal` to the calling thread now ends its process,
/// by an action left at a default that terminates or dumps core: `None` when
/// it does not, else whether the kernel's signal state also shows that
/// resuming the thread with `signal` carries the action out
/// ([`KernelSignalState::delivery_carries_out_a_fatal_default`]), asked only
/// when `may_retire_others`. Detcore's copy of the dispositions answers the
/// first question without a read for most deliveries (a handled or ignored
/// signal); the kernel's state is read at most once.
pub(crate) fn fatal_default_delivery<G, T>(
    guest: &G,
    signal: i32,
    may_retire_others: bool,
) -> Option<bool>
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    match fatal_delivery_observation(guest, signal, may_retire_others) {
        FatalDeliveryObservation::Fatal { may_retire_others } => Some(may_retire_others),
        FatalDeliveryObservation::Nonfatal | FatalDeliveryObservation::Unknown => None,
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum FatalDeliveryObservation {
    Nonfatal,
    Fatal { may_retire_others: bool },
    Unknown,
}

/// Keep unavailable native/copy evidence distinct from a known nonfatal
/// disposition. The old scheduler decision retains its exact Option mapping.
pub(crate) fn fatal_delivery_observation<G, T>(
    guest: &G,
    signal: i32,
    may_retire_others: bool,
) -> FatalDeliveryObservation
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    let copied = super::signal_shadow::copied_dispositions_for(guest, signal)
        .map(|copied| default_action_ends_process(copied.ignored, copied.caught, signal));
    if copied == Some(false) {
        return FatalDeliveryObservation::Nonfatal;
    }
    let kernel = (copied.is_none() || may_retire_others)
        .then(|| read_thread_signal_state(guest.pid(), guest.tid()).ok())
        .flatten();
    match copied.or_else(|| kernel.map(|state| state.default_action_ends_process(signal))) {
        Some(true) => FatalDeliveryObservation::Fatal {
            may_retire_others: may_retire_others
                && kernel.is_some_and(|state| state.delivery_carries_out_a_fatal_default(signal)),
        },
        Some(false) => FatalDeliveryObservation::Nonfatal,
        None => FatalDeliveryObservation::Unknown,
    }
}

fn signal_has_uncatchable_default_disposition(signal: SigWrapper) -> bool {
    matches!(signal.raw(), libc::SIGKILL | libc::SIGSTOP)
}

pub(super) async fn wait_signal_disposition<G, T>(
    guest: &mut G,
    status: ResumeStatus,
    guest_signal_mask: &KernelSigset,
    action_addr: AddrMut<'_, KernelSigaction>,
    inspect_action: bool,
) -> Result<Option<WaitSignalDisposition>, Error>
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    let ResumeStatus::Signaled(signals) = status else {
        return Ok(None);
    };
    let Some(mut signals) = signals else {
        return Ok(Some(WaitSignalDisposition::Interrupt));
    };
    signals.sort_by_key(|signal| signal.raw());
    for signal in signals {
        if signal_is_blocked(guest_signal_mask, signal) {
            continue;
        }
        if signal_has_uncatchable_default_disposition(signal) {
            return Ok(Some(WaitSignalDisposition::Interrupt));
        }
        if !inspect_action {
            return Ok(Some(WaitSignalDisposition::Interrupt));
        }
        let call = syscalls::RtSigaction::new()
            .with_signum(signal.raw())
            .with_action(None)
            .with_old_action(Some(action_addr.cast()))
            .with_sigsetsize(std::mem::size_of::<u64>());
        guest.inject_with_retry(call).await?;
        let action: KernelSigaction = guest.memory().read_value(action_addr)?;
        if action.handler == libc::SIG_IGN as u64
            || action.handler == libc::SIG_DFL as u64
                && signal_default_disposition_does_not_interrupt_child_wait(signal)
        {
            continue;
        }
        return Ok(Some(
            if action.handler != libc::SIG_DFL as u64 && action.flags & libc::SA_RESTART as u64 != 0
            {
                WaitSignalDisposition::Restart
            } else {
                WaitSignalDisposition::Interrupt
            },
        ));
    }
    Ok(None)
}

/// The signals a precise futex wait holds in its own check after a wake:
/// `SIGCHLD` and every signal a host-timed source can post (`host_timed`),
/// except a signal the scheduler committed to it at the wake (`committed`)
/// that no host-timed source can post too
/// (https://github.com/rrnewton/hermit/issues/4005).
pub(crate) fn futex_wait_held_after_wake(
    host_timed: KernelSigset,
    committed: KernelSigset,
) -> KernelSigset {
    (kernel_sigset_bit(libc::SIGCHLD) | host_timed) & !(committed & !host_timed)
}

/// The signals that end a precise futex wait at its own check: those pending
/// and interrupting it (`interrupting`) that it does not hold (`held`), or,
/// when there are none, a guest's thread-directed `SIGCHLD` in its private
/// queue that the schedule recorded (`PrivatePending`). Such a copy may have
/// been sent before this wait parked, and the drain that ends a parked wait for
/// it never saw this wait, so only this check can. `/proc` cannot tell it from
/// a copy a host-timed source posted, so its bit only prompts the question
/// (https://github.com/rrnewton/hermit/issues/4132).
///
/// A pending copy Linux discarded when it was sent does not end the wait,
/// whatever handler exists now: the scheduler's record of such copies
/// (`DiscardedSignalControl::Bits`) is subtracted, per queue, from every
/// signal (`without_discarded`,
/// <https://github.com/rrnewton/hermit/issues/4293>).
pub(crate) async fn futex_wait_pending_signals<G, T>(
    guest: &mut G,
    state: &KernelSignalState,
    interrupting: KernelSigset,
    held: KernelSigset,
    host_timed: KernelSigset,
    committed: KernelSigset,
) -> KernelSigset
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    let pending = without_discarded(guest, state, interrupting & !held, committed).await;
    let sigchld = kernel_sigset_bit(libc::SIGCHLD) & !host_timed;
    if pending == 0
        && interrupting & state.thread_pending & held & sigchld != 0
        && matches!(
            crate::tool_global::child_exit_sigchld(
                guest,
                crate::scheduler::child_exit_sigchld::ChildExitSigchldControl::PrivatePending,
            )
            .await,
            crate::scheduler::child_exit_sigchld::ChildExitSigchldAnswer::Placed(true)
        )
    {
        return sigchld;
    }
    pending
}

/// `pending`, a set of this thread's pending signals, without each one whose
/// only pending copies Linux discarded when they were sent, as the scheduler
/// recorded them (`scheduler::discarded_at_send`). Asks the scheduler only
/// when such a signal could be there.
///
/// No signal is exempt, not even one the wake's answer names: that answer
/// carries the drain's batch too, whose copy a sender may have flushed
/// (`SIG_IGN`) and sent again, discarded, before this check; Linux then has
/// no copy to deliver (the Claude re-check of the R2b-1 design, R4-1,
/// https://github.com/rrnewton/hermit/issues/4273). A copy the scheduler
/// itself sent kept clears its bit, so applying the record to it changes
/// nothing. `committed` is kept for the callers' hold and is not used here.
pub(crate) async fn without_discarded<G, T>(
    guest: &mut G,
    state: &KernelSignalState,
    pending: KernelSigset,
    committed: KernelSigset,
) -> KernelSigset
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    use crate::scheduler::discarded_at_send::DiscardedSignalAnswer;
    use crate::scheduler::discarded_at_send::DiscardedSignalControl;
    use crate::scheduler::discarded_at_send::STANDARD_SIGNALS;
    if pending & STANDARD_SIGNALS == 0
        || !crate::scheduler::discarded_at_send::records(guest.config())
    {
        return pending;
    }
    let DiscardedSignalAnswer::Bits { thread, process } =
        crate::tool_global::discarded_signal(guest, DiscardedSignalControl::Bits).await
    else {
        return pending;
    };
    with_kept_copies(state, thread, process, pending, committed)
}

/// `pending` without each signal whose only pending copies the record marks
/// as discarded at send (`thread` for the thread's queue, `process` for the
/// shared queue). The pure part of `without_discarded`. No signal is exempt,
/// not even one in `committed`, the set the wake's answer names, which can
/// hold a drain batch's copy that was flushed and sent again, discarded
/// (R4-1 of the R2b-1 design re-checks,
/// <https://github.com/rrnewton/hermit/issues/4273>).
pub(crate) fn with_kept_copies(
    state: &KernelSignalState,
    thread: u64,
    process: u64,
    pending: KernelSigset,
    committed: KernelSigset,
) -> KernelSigset {
    let _ = committed;
    let kept = (state.thread_pending & !thread) | (state.shared_pending & !process);
    pending & kept
}

/// The one-bit kernel sigset for `raw_signal` (1-based), or 0 when out of range.
pub(crate) fn kernel_sigset_bit(raw_signal: i32) -> KernelSigset {
    if (1..=KernelSigset::BITS as i32).contains(&raw_signal) {
        1_u64 << (raw_signal as u32 - 1)
    } else {
        0
    }
}

/// The exit signal that a child created by this clone-family call sends to
/// the calling process when it exits, at a moment set by host timing, as a
/// kernel sigset; 0 when there is none to hold. Linux sends a child's exit
/// signal to the process that created it. A thread (`CLONE_THREAD`) sends
/// none. SIGCHLD is already held in every gated wait. A `CLONE_PARENT` child
/// sends the caller's own exit signal to the caller's parent instead, and that
/// signal is SIGCHLD or was recorded for that parent when it created the
/// caller's process (a reparent to another process resets it to SIGCHLD).
pub(crate) fn clone_host_timed_signals(
    flags: CloneFlags,
    exit_signal: libc::c_int,
) -> KernelSigset {
    if flags.intersects(CloneFlags::CLONE_THREAD | CloneFlags::CLONE_PARENT)
        || exit_signal == libc::SIGCHLD
    {
        0
    } else {
        kernel_sigset_bit(exit_signal)
    }
}

/// One thread's signal state as the kernel reports it in
/// `/proc/<pid>/task/<tid>/status`.
///
/// The kernel is the authority for a guest thread's mask, dispositions, and
/// pending signals on backends that run the guest as real host threads. Reading
/// the state has no effect on the guest, unlike a probe syscall around which a
/// signal can be dequeued and held by the backend
/// (https://github.com/rrnewton/hermit/issues/3146).
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub(crate) struct KernelSignalState {
    /// Signals pending for the thread or its whole thread group (`SigPnd | ShdPnd`).
    pub(crate) pending: KernelSigset,
    /// Signals pending on the thread's private queue (`SigPnd`).
    pub(crate) thread_pending: KernelSigset,
    /// Signals pending on the thread group's shared queue (`ShdPnd`).
    pub(crate) shared_pending: KernelSigset,
    /// The thread's current signal mask (`SigBlk`).
    pub(crate) blocked: KernelSigset,
    /// Signals whose disposition is `SIG_IGN` (`SigIgn`).
    pub(crate) ignored: KernelSigset,
    /// Signals with a handler installed (`SigCgt`).
    pub(crate) caught: KernelSigset,
}

/// [`KernelSignalState::default_action_ends_process`] given only the
/// thread's ignored and caught sets, from wherever they come (the kernel's
/// `/proc` view or Detcore's copy, `signal_shadow::copied_dispositions`).
pub(crate) fn default_action_ends_process(
    ignored: KernelSigset,
    caught: KernelSigset,
    signal: i32,
) -> bool {
    let bit = kernel_sigset_bit(signal);
    let stops_or_continues = [
        libc::SIGSTOP,
        libc::SIGTSTP,
        libc::SIGTTIN,
        libc::SIGTTOU,
        libc::SIGCONT,
    ]
    .into_iter()
    .fold(0, |set, signal| set | kernel_sigset_bit(signal));
    signal == libc::SIGKILL
        || ((ignored | caught | default_ignored_signals() | stops_or_continues) & bit) == 0
}

/// The signals a process with dispositions `ignored` and `caught` discards
/// when they are generated and unblocked: those set to `SIG_IGN`, and the
/// default-ignored ones with no handler (`sig_task_ignored`).
pub(crate) fn ignored_at_generation(ignored: KernelSigset, caught: KernelSigset) -> KernelSigset {
    ignored | (default_ignored_signals() & !caught)
}

impl KernelSignalState {
    /// Parse the five signal lines of a `/proc/<pid>/task/<tid>/status` file.
    pub(crate) fn parse(status: &str) -> Option<Self> {
        let mut thread_pending = None;
        let mut shared_pending = None;
        let mut state = KernelSignalState::default();
        let mut blocked = None;
        let mut ignored = None;
        let mut caught = None;
        for line in status.lines() {
            let Some((key, value)) = line.split_once(':') else {
                continue;
            };
            let slot = match key {
                "SigPnd" => &mut thread_pending,
                "ShdPnd" => &mut shared_pending,
                "SigBlk" => &mut blocked,
                "SigIgn" => &mut ignored,
                "SigCgt" => &mut caught,
                _ => continue,
            };
            *slot = Some(KernelSigset::from_str_radix(value.trim(), 16).ok()?);
        }
        state.thread_pending = thread_pending?;
        state.shared_pending = shared_pending?;
        state.pending = state.thread_pending | state.shared_pending;
        state.blocked = blocked?;
        state.ignored = ignored?;
        state.caught = caught?;
        Some(state)
    }

    /// Signals whose delivery, while unblocked in `mask`, ends a blocking wait: a
    /// caught signal runs its handler, and a `SIG_DFL` signal terminates, dumps
    /// core, or stops the process. Ignored signals and the default-ignored
    /// `SIGCHLD`, `SIGCONT`, `SIGURG`, and `SIGWINCH` do not, and neither does the
    /// backend's own preemption signal.
    pub(crate) fn interrupting(&self, mask: KernelSigset) -> KernelSigset {
        let default_action = !(self.ignored | self.caught);
        (self.caught | (default_action & !default_ignored_signals()))
            & !mask
            & !kernel_sigset_bit(reverie::PERF_EVENT_SIGNAL as i32)
    }

    /// Signals Linux discards when they are generated while unblocked: those
    /// set to `SIG_IGN`, and the default-ignored `SIGCHLD`, `SIGCONT`, `SIGURG`
    /// and `SIGWINCH` while they have no handler (`sig_task_ignored`). A blocked
    /// signal is never discarded, since its disposition may change before it is
    /// unblocked. Under ptrace the kernel queues even these for the tracer, so
    /// the pending set alone does not show the discard.
    pub(crate) fn discarded_at_generation(&self) -> KernelSigset {
        self.ignored_at_generation() & !self.blocked
    }

    /// The signals [`discarded_at_generation`](Self::discarded_at_generation)
    /// names, before the mask: those set to `SIG_IGN`, and the default-ignored
    /// ones with no handler. A caller that knows a better mask than `SigBlk`
    /// (`scheduler::discarded_at_send`) applies its own.
    pub(crate) fn ignored_at_generation(&self) -> KernelSigset {
        ignored_at_generation(self.ignored, self.caught)
    }

    /// Whether delivering `signal` now ends the process: its disposition is
    /// `SIG_DFL` and its default action terminates or dumps core, not ignores,
    /// stops or continues. `SIGKILL` always does.
    pub(crate) fn default_action_ends_process(&self, signal: i32) -> bool {
        default_action_ends_process(self.ignored, self.caught, signal)
    }

    /// Whether resuming the thread from a delivery stop with `signal` makes
    /// the kernel carry out its default action and end the process: the
    /// thread does not block `signal`, which `ptrace_signal` would requeue,
    /// and [`Self::default_action_ends_process`].
    pub(crate) fn delivery_carries_out_a_fatal_default(&self, signal: i32) -> bool {
        self.blocked & kernel_sigset_bit(signal) == 0 && self.default_action_ends_process(signal)
    }

    /// The job-control stop signals `SIGTSTP`, `SIGTTIN`, and `SIGTTOU` whose
    /// disposition is still `SIG_DFL`.
    ///
    /// Linux does not stop a process for one of these when its process group is
    /// orphaned: `get_signal` discards the signal (`is_current_pgrp_orphaned`),
    /// and a wait it reached restarts as if no signal had arrived. Whether a
    /// group is orphaned depends on the parents and sessions of every process in
    /// it, which Detcore does not track.
    pub(crate) fn default_job_control_stops(&self) -> KernelSigset {
        [libc::SIGTSTP, libc::SIGTTIN, libc::SIGTTOU]
            .into_iter()
            .fold(0, |set, signal| set | kernel_sigset_bit(signal))
            & !(self.ignored | self.caught)
    }

    /// The signals that end a blocking wait under the guest's `mask`: those
    /// [`interrupting`](Self::interrupting) names, without the default job-control
    /// stops ([`default_job_control_stops`](Self::default_job_control_stops)) when
    /// `defers_default_stops` is set.
    ///
    /// A wait sets it when Linux's restart of the call keeps its deadline
    /// (`NonblockableSyscall::restart_keeps_deadline`): a `poll` with a positive
    /// timeout, and a timed futex wait. Detcore keeps that deadline for the
    /// kernel's restart only when the wait ends with `ERESTART_RESTARTBLOCK`, which
    /// a stop signal the backend holds does not (`held_signal_restart_errno`), so
    /// ending such a wait for a default stop that Linux discards in an orphaned
    /// process group could restart it with a fresh timeout, and it would return
    /// late. Left alone, the wait keeps its deadline, as on hermit main, and a stop
    /// that Linux does not discard takes effect when the call returns rather than
    /// when the signal arrives (https://github.com/rrnewton/hermit/issues/3358).
    /// `SIGSTOP`, a caught stop signal, and a fatal one still end the wait.
    pub(crate) fn interrupting_wait(
        &self,
        mask: KernelSigset,
        defers_default_stops: bool,
    ) -> KernelSigset {
        let interrupting = self.interrupting(mask);
        if defers_default_stops {
            interrupting & !self.default_job_control_stops()
        } else {
            interrupting
        }
    }

    /// Pending signals that would end a blocking wait under the guest's `mask`
    /// (see [`interrupting_wait`](Self::interrupting_wait)).
    pub(crate) fn pending_interrupting(
        &self,
        mask: KernelSigset,
        defers_default_stops: bool,
    ) -> KernelSigset {
        self.pending & self.interrupting_wait(mask, defers_default_stops)
    }

    /// The signal the kernel dequeues next for this thread while `mask` is
    /// blocked, and the queue it comes from, or `None` if no unblocked signal is
    /// pending.
    ///
    /// As in `dequeue_signal` and `next_signal` (`kernel/signal.c`), the thread's
    /// private queue goes before the thread group's shared queue, and within a
    /// queue a synchronous signal (`SIGSEGV`, `SIGBUS`, `SIGILL`, `SIGTRAP`,
    /// `SIGFPE`, `SIGSYS`) goes before the lowest-numbered other one.
    pub(crate) fn next_dequeued(&self, mask: KernelSigset) -> Option<(i32, SignalQueue)> {
        let synchronous = SYNCHRONOUS_SIGNALS
            .into_iter()
            .fold(0, |set, signal| set | kernel_sigset_bit(signal));
        let first = |queued: KernelSigset| {
            let deliverable = queued & !mask;
            let preferred = if deliverable & synchronous != 0 {
                deliverable & synchronous
            } else {
                deliverable
            };
            (preferred != 0).then(|| preferred.trailing_zeros() as i32 + 1)
        };
        first(self.thread_pending)
            .map(|signal| (signal, SignalQueue::Thread))
            .or_else(|| first(self.shared_pending).map(|signal| (signal, SignalQueue::Shared)))
    }

    /// The signals pending on `queue`.
    pub(crate) fn queued(&self, queue: SignalQueue) -> KernelSigset {
        match queue {
            SignalQueue::Thread => self.thread_pending,
            SignalQueue::Shared => self.shared_pending,
        }
    }
}

/// The signals whose default action ignores them.
pub(crate) fn default_ignored_signals() -> KernelSigset {
    [libc::SIGCHLD, libc::SIGCONT, libc::SIGURG, libc::SIGWINCH]
        .into_iter()
        .fold(0, |set, signal| set | kernel_sigset_bit(signal))
}

/// The signals an instruction raises, which the kernel dequeues before any other
/// signal on the same queue (`SYNCHRONOUS_MASK` in `kernel/signal.c`).
const SYNCHRONOUS_SIGNALS: [i32; 6] = [
    libc::SIGSEGV,
    libc::SIGBUS,
    libc::SIGILL,
    libc::SIGTRAP,
    libc::SIGFPE,
    libc::SIGSYS,
];

/// One of a thread's two queues of pending signals.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum SignalQueue {
    /// The thread's private queue (`SigPnd`).
    Thread,
    /// The thread group's shared queue (`ShdPnd`).
    Shared,
}

/// Set once per Hermit process, by [`refuse_host_signal_state_reads`], when
/// the backend's guest thread IDs do not name host tasks (KVM): a host
/// `/proc/<pid>/task/<tid>/status` would then describe an unrelated host task,
/// if any, chosen by host thread-ID allocation, so its signal state must never
/// decide a guest-visible outcome. Every read that exists today is gated off on
/// such a backend by a capability (`Config::models_signal_targets`,
/// `supports_blocked_wait_signal_interruption` or one of the four capabilities
/// split out of it, `reports_child_exit_publication`, a
/// nested PID namespace, or the guard in
/// `restartable_internal_io_interrupting_signals`); this latch is the backstop
/// for a future path that misses its gate.
#[cfg(not(test))]
static HOST_SIGNAL_STATE_READS_REFUSED: std::sync::atomic::AtomicBool =
    std::sync::atomic::AtomicBool::new(false);

#[cfg(test)]
thread_local! {
    /// The latch for unit tests, per test thread, so that tests reading their
    /// own real `/proc` state run beside one that sets it.
    static HOST_SIGNAL_STATE_READS_REFUSED_FOR_TEST: std::cell::Cell<bool> =
        const { std::cell::Cell::new(false) };
}

/// Whether a backend with `backend`'s capabilities forbids host `/proc` signal
/// state reads for its guest threads: exactly when its guest thread IDs do not
/// name host tasks (`procfs_inode::guest_tids_name_host_tasks`).
pub(crate) fn refuses_host_signal_state_reads(backend: &BackendCapabilities) -> bool {
    !crate::procfs_inode::guest_tids_name_host_tasks(backend, None)
}

/// Latch the refusal for this process when `backend` forbids host `/proc`
/// signal state reads ([`refuses_host_signal_state_reads`]). Called once, when
/// Detcore's global state is created for a run.
pub(crate) fn refuse_host_signal_state_reads(backend: &BackendCapabilities) {
    if !refuses_host_signal_state_reads(backend) {
        return;
    }
    #[cfg(not(test))]
    HOST_SIGNAL_STATE_READS_REFUSED.store(true, std::sync::atomic::Ordering::Relaxed);
    #[cfg(test)]
    HOST_SIGNAL_STATE_READS_REFUSED_FOR_TEST.with(|refused| refused.set(true));
}

/// Whether host `/proc` signal state reads are refused in this process
/// ([`refuse_host_signal_state_reads`]).
pub(crate) fn host_signal_state_reads_refused() -> bool {
    #[cfg(not(test))]
    {
        HOST_SIGNAL_STATE_READS_REFUSED.load(std::sync::atomic::Ordering::Relaxed)
    }
    #[cfg(test)]
    {
        HOST_SIGNAL_STATE_READS_REFUSED_FOR_TEST.with(|refused| refused.get())
    }
}

/// Read `tid`'s signal state from the kernel.
///
/// On a backend whose guest thread IDs do not name host tasks
/// ([`host_signal_state_reads_refused`]) the read is refused with `ENOSYS`
/// before it reaches `/proc`: a caller that needs the state ends the run by
/// name (`BlockedWaitSignalError::StateUnreadable`), and one that treats an
/// unreadable state as unknown keeps its documented fallback. Either way no
/// unrelated host task's state reaches a decision.
pub(crate) fn read_kernel_signal_state(pid: Pid, tid: Pid) -> Result<KernelSignalState, Errno> {
    #[cfg(test)]
    if let Some(result) = signal_state_read_seam::scripted(pid, tid) {
        return result;
    }
    if host_signal_state_reads_refused() {
        static REPORTED: std::sync::Once = std::sync::Once::new();
        REPORTED.call_once(|| {
            error!(
                "refused a host /proc signal state read of guest thread {} (process {}): this \
                 backend's guest thread IDs do not name host tasks",
                tid.as_raw(),
                pid.as_raw()
            );
        });
        return Err(Errno::ENOSYS);
    }
    let status = status_files::read(pid, tid)?;
    KernelSignalState::parse(&status).ok_or(Errno::EIO)
}

/// Drop thread `tid`'s open status files (`status_files`). Called when the
/// thread exits; a later read of a reused TID opens the file afresh.
pub(crate) fn forget_thread_status(tid: Pid) {
    status_files::forget(tid);
}

/// Keep status files open from now on, in this process (`status_files`).
/// Only a process that never shares a guest's descriptor table may call this:
/// Hermit's own process, where Detcore traces the guest from outside. Detcore
/// linked into a guest (the in-guest runtimes) never calls it, so it reads the
/// path each time and no descriptor of its appears in the guest's table.
pub(crate) fn keep_status_files_open() {
    status_files::enable();
}

/// `/proc/<pid>/task/<tid>/status`, kept open per traced thread, so that a
/// signal-state read is one pread(2) at offset 0 rather than an open(2),
/// read(2) and close(2). A gated wait reads its thread's state at every turn,
/// and every open(2) runs the host's file-open security hooks: measured on
/// 2026-10-24, Hermit spent 20.7% of its samples opening this file and 18.5% in
/// security_file_open alone, and on hosts where a BPF file-open hook takes its
/// slow path (a mount walk and a contended map update) the same opens made the
/// inherited-terminal poll tests of hermit-cli/tests/external_signal_interrupt.rs
/// spend six times their ordinary system CPU.
///
/// An open procfs task file stays bound to the task it was opened for: after
/// that thread exits it reads ESRCH, never a later task given the same TID. So
/// a failed read drops the entry and opens the path once more, which reads
/// exactly what reading the path did before this cache. At most `CAPACITY`
/// files are kept, so a guest with many threads cannot exhaust Hermit's own
/// descriptors; past that, reads open the path as before.
///
/// Files are kept only once `enable` has run in the process, which Hermit's
/// own binary does at startup ([`keep_status_files_open`]). Where Detcore runs
/// inside the guest (liteinst, in-guest-trap, DBT, SaBRe), a kept file would
/// be a descriptor in the guest's own table, visible to it and inherited by its
/// children; there nothing enables keeping, every read is the plain
/// `read_to_string` of the path, and the map is never created (a `BTreeMap`,
/// so no hasher state either).
mod status_files {
    use std::collections::BTreeMap;
    use std::fs::File;
    use std::os::unix::fs::FileExt;
    use std::sync::Arc;
    use std::sync::LazyLock;
    use std::sync::Mutex;

    use reverie::Pid;
    use reverie::syscalls::Errno;

    /// The most status files kept open at once.
    pub(super) const CAPACITY: usize = 256;

    /// The kept files, by (pid, tid).
    type Kept = BTreeMap<(i32, i32), Arc<File>>;

    static OPEN: LazyLock<Mutex<Kept>> = LazyLock::new(|| Mutex::new(BTreeMap::new()));

    /// Whether this process keeps files (`enable`).
    #[cfg(not(test))]
    static KEEPS: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

    #[cfg(test)]
    thread_local! {
        /// The switch for unit tests, per test thread, so that a test that
        /// keeps no files runs beside one that keeps them.
        static KEEPS_FOR_TEST: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
    }

    /// Keep files from now on (`keep_status_files_open`).
    pub(super) fn enable() {
        #[cfg(not(test))]
        KEEPS.store(true, std::sync::atomic::Ordering::Relaxed);
        #[cfg(test)]
        KEEPS_FOR_TEST.with(|keeps| keeps.set(true));
    }

    fn enabled() -> bool {
        #[cfg(not(test))]
        {
            KEEPS.load(std::sync::atomic::Ordering::Relaxed)
        }
        #[cfg(test)]
        {
            KEEPS_FOR_TEST.with(|keeps| keeps.get())
        }
    }

    fn open() -> std::sync::MutexGuard<'static, Kept> {
        OPEN.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
    }

    /// The whole file, read from offset 0. procfs regenerates a status file
    /// for every read that starts at offset 0.
    fn read_whole(file: &File) -> std::io::Result<String> {
        let mut bytes = Vec::with_capacity(4096);
        loop {
            let filled = bytes.len();
            bytes.resize(filled + 4096, 0);
            let read = file.read_at(&mut bytes[filled..], filled as u64)?;
            bytes.truncate(filled + read);
            if read == 0 {
                break;
            }
        }
        String::from_utf8(bytes)
            .map_err(|error| std::io::Error::new(std::io::ErrorKind::InvalidData, error))
    }

    /// Thread `tid`'s status file text. `ESRCH` when it cannot be read, as
    /// when the path could not be read before this cache.
    pub(super) fn read(pid: Pid, tid: Pid) -> Result<String, Errno> {
        if !enabled() {
            let path = format!("/proc/{}/task/{}/status", pid.as_raw(), tid.as_raw());
            return std::fs::read_to_string(path).map_err(|_| Errno::ESRCH);
        }
        let key = (pid.as_raw(), tid.as_raw());
        let kept = open().get(&key).cloned();
        if let Some(file) = kept {
            if let Ok(text) = read_whole(&file)
                && !text.is_empty()
            {
                return Ok(text);
            }
            open().remove(&key);
        }
        let path = format!("/proc/{}/task/{}/status", key.0, key.1);
        let file = File::open(path).map_err(|_| Errno::ESRCH)?;
        let text = read_whole(&file).map_err(|_| Errno::ESRCH)?;
        let mut files = open();
        if files.len() < CAPACITY {
            files.insert(key, Arc::new(file));
        }
        Ok(text)
    }

    /// Drop every kept file of thread `tid`.
    pub(super) fn forget(tid: Pid) {
        if !enabled() {
            return;
        }
        open().retain(|&(_, kept_tid), _| kept_tid != tid.as_raw());
    }

    /// How many files are kept open now.
    #[cfg(test)]
    pub(super) fn kept() -> usize {
        open().len()
    }

    /// Whether a file of thread `tid` of process `pid` is kept open.
    #[cfg(test)]
    pub(super) fn keeps(pid: Pid, tid: Pid) -> bool {
        open().contains_key(&(pid.as_raw(), tid.as_raw()))
    }

    /// The kept file of thread `tid` of process `pid`, if one is kept, for a
    /// test to read without the fallback to the path.
    #[cfg(test)]
    pub(super) fn kept_file(pid: Pid, tid: Pid) -> Option<Arc<File>> {
        open().get(&(pid.as_raw(), tid.as_raw())).cloned()
    }

    /// `read_whole`, for tests.
    #[cfg(test)]
    pub(super) fn read_kept(file: &File) -> std::io::Result<String> {
        read_whole(file)
    }
}

/// Why a blocked wait ended the run instead of returning to the guest
/// (https://github.com/rrnewton/hermit/issues/3146). A wait call cannot return
/// the underlying error natively, and resuming the guest after the second
/// failure would leave every blockable signal blocked in it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum BlockedWaitSignalError {
    /// The thread still exists, but its signal state could not be read from
    /// `/proc` (`errno` is `ESRCH` for an unreadable file, `EIO` for one that
    /// does not parse).
    StateUnreadable { pid: Pid, tid: Pid, errno: Errno },
    /// The guest's own signal mask could not be put back after the wait blocked
    /// every signal. `last_error` is the last injected call's error.
    MaskNotRestored {
        pid: Pid,
        tid: Pid,
        attempts: usize,
        last_error: Option<Errno>,
    },
}

impl std::fmt::Display for BlockedWaitSignalError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::StateUnreadable { pid, tid, errno } => write!(
                f,
                "cannot read the signal state of guest thread {tid} (process {pid}) from \
                 /proc while it waits: {errno}"
            ),
            Self::MaskNotRestored {
                pid,
                tid,
                attempts,
                last_error,
            } => {
                write!(
                    f,
                    "cannot restore the signal mask of guest thread {tid} (process {pid}) \
                     after a blocked wait ({attempts} attempts"
                )?;
                if let Some(errno) = last_error {
                    write!(f, ", last error {errno}")?;
                }
                f.write_str("); it would resume with every signal blocked")
            }
        }
    }
}

impl std::error::Error for BlockedWaitSignalError {}

/// Whether thread `tid` of process `pid` no longer exists.
pub(crate) fn guest_thread_is_gone(pid: Pid, tid: Pid) -> bool {
    // SAFETY: signal 0 only checks that the thread exists and may be signalled.
    let result = unsafe { libc::syscall(libc::SYS_tgkill, pid.as_raw(), tid.as_raw(), 0) };
    result == -1 && std::io::Error::last_os_error().raw_os_error() == Some(libc::ESRCH)
}

/// Read `tid`'s signal state when `pid` may not be its thread group.
///
/// Reverie can report the creating process's pid for a process that a raw
/// `clone` without `CLONE_THREAD` created, so `/proc/<pid>/task/<tid>` does not
/// exist although the thread does. `/proc/<tid>/task/<tid>` names any live
/// thread, its own thread group's leader or not, so it is read before the
/// thread is taken to be gone (https://github.com/rrnewton/hermit/issues/3982).
pub(crate) fn read_thread_signal_state(pid: Pid, tid: Pid) -> Result<KernelSignalState, Errno> {
    read_kernel_signal_state(pid, tid).or_else(|error| {
        if pid == tid {
            Err(error)
        } else {
            read_kernel_signal_state(tid, tid)
        }
    })
}

/// Whether thread `tid` no longer exists, when `pid` may not be its thread
/// group ([`read_thread_signal_state`]). `tkill` names the thread without a
/// thread group, so a live thread under a wrong `pid` is not taken to be gone.
pub(crate) fn thread_is_gone(pid: Pid, tid: Pid) -> bool {
    if !guest_thread_is_gone(pid, tid) {
        return false;
    }
    // SAFETY: signal 0 only checks that the thread exists and may be signalled.
    let result = unsafe { libc::syscall(libc::SYS_tkill, tid.as_raw(), 0) };
    result == -1 && std::io::Error::last_os_error().raw_os_error() == Some(libc::ESRCH)
}

/// [`read_wait_signal_state`] for a thread whose reported `pid` may not be its
/// thread group ([`read_thread_signal_state`]).
pub(crate) fn read_thread_wait_signal_state(
    pid: Pid,
    tid: Pid,
) -> Result<KernelSignalState, Error> {
    match read_thread_signal_state(pid, tid) {
        Ok(state) => Ok(state),
        Err(_) if thread_is_gone(pid, tid) => Err(Errno::ERESTARTNOINTR.into()),
        Err(errno) => Err(Error::Tool(anyhow::Error::new(
            BlockedWaitSignalError::StateUnreadable { pid, tid, errno },
        ))),
    }
}

/// Read the signal state of `tid`, which is stopped inside a blocked wait.
///
/// The read's own error never reaches the guest, because no wait call returns
/// `ESRCH` or `EIO` for it. If the thread no longer exists (it was killed while
/// it waited), the call ends with `ERESTARTNOINTR`, which no thread observes.
/// Otherwise the run ends with [`BlockedWaitSignalError::StateUnreadable`].
pub(crate) fn read_wait_signal_state(pid: Pid, tid: Pid) -> Result<KernelSignalState, Error> {
    match read_kernel_signal_state(pid, tid) {
        Ok(state) => Ok(state),
        Err(_) if guest_thread_is_gone(pid, tid) => Err(Errno::ERESTARTNOINTR.into()),
        Err(errno) => Err(Error::Tool(anyhow::Error::new(
            BlockedWaitSignalError::StateUnreadable { pid, tid, errno },
        ))),
    }
}

/// A test seam in front of the `/proc` read in [`read_kernel_signal_state`].
#[cfg(test)]
pub(crate) mod signal_state_read_seam {
    use std::cell::RefCell;

    use reverie::Pid;
    use reverie::syscalls::Errno;

    use super::KernelSignalState;

    type Script = Box<dyn FnMut(Pid, Pid) -> Option<Result<KernelSignalState, Errno>>>;

    thread_local! {
        static SCRIPT: RefCell<Option<Script>> = const { RefCell::new(None) };
    }

    /// Removes the installed script when dropped.
    pub(crate) struct Installed(());

    impl Drop for Installed {
        fn drop(&mut self) {
            SCRIPT.with(|script| script.borrow_mut().take());
        }
    }

    /// Answer this thread's reads with `script`; `None` falls through to `/proc`.
    pub(crate) fn install(
        script: impl FnMut(Pid, Pid) -> Option<Result<KernelSignalState, Errno>> + 'static,
    ) -> Installed {
        SCRIPT.with(|slot| *slot.borrow_mut() = Some(Box::new(script)));
        Installed(())
    }

    pub(super) fn scripted(pid: Pid, tid: Pid) -> Option<Result<KernelSignalState, Errno>> {
        SCRIPT.with(|slot| {
            slot.borrow_mut()
                .as_mut()
                .and_then(|script| script(pid, tid))
        })
    }
}

pub(super) fn blocked_signal_mask() -> KernelSigset {
    // Preserve libc's definition of the blockable set (notably its reserved
    // NPTL signals) while converting the result to the kernel's one-word ABI.
    let mut libc_mask: libc::sigset_t = unsafe { std::mem::zeroed() };
    unsafe {
        libc::sigfillset(&mut libc_mask);
        libc::sigdelset(&mut libc_mask, reverie::PERF_EVENT_SIGNAL as i32);
    }
    (1..=KernelSigset::BITS as i32).fold(0, |mask, raw_signal| {
        if unsafe { libc::sigismember(&libc_mask, raw_signal) } == 1 {
            mask | (1_u64 << (raw_signal as u32 - 1))
        } else {
            mask
        }
    })
}

/// Whether a managed child wait reads the guest's mask without replacing it
/// (`block_signals_for_disposition`), and so restores nothing after:
/// - on a backend whose application signals the runtime already holds while
///   the callback runs (DBT, `requires_thread_directed_process_signals`);
/// - under the in-guest delivery gate (A5 step 3c.1e B,
///   <https://github.com/rrnewton/hermit/issues/4485>): the in-guest runtime
///   runs every callback under its own mask, which blocks every blockable
///   guest signal, so the guest's are held already; the query is answered from
///   the guest's saved mask (`Guest::resume_signal_mask`'s record), and a
///   block would make the mask the request publishes, and the guest resumes
///   under, "every signal blocked" until the restore.
fn reads_mask_in_place(config: &Config) -> bool {
    config.backend.requires_thread_directed_process_signals || config.in_guest_signal_delivery
}

pub(super) async fn block_signals_for_disposition<G, T>(
    guest: &mut G,
    blocked_mask_addr: Addr<'_, KernelSigset>,
    old_mask_addr: AddrMut<'_, KernelSigset>,
) -> Result<KernelSigset, Error>
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    let block_signals = syscalls::RtSigprocmask::new()
        .with_how(libc::SIG_SETMASK)
        .with_set((!reads_mask_in_place(guest.config())).then_some(blocked_mask_addr.cast()))
        .with_oldset(Some(old_mask_addr.cast()))
        .with_sigsetsize(KERNEL_SIGSET_SIZE);
    guest.inject_with_retry(block_signals).await?;
    let guest_mask: KernelSigset = guest.memory().read_value(old_mask_addr)?;
    if guest.config().backend.reports_child_exit_publication
        || crate::scheduler::discarded_at_send::records(guest.config())
    {
        // While the private mask is installed, the kernel reports Detcore's
        // mask for this thread; the scheduler's child-exit classification and
        // its record of copies Linux discarded at send must read the guest's
        // own (the Claude re-check of the R2b-1 design, R4-3).
        crate::tool_global::set_saved_guest_sigmask(guest, Some(guest_mask)).await;
    }
    Ok(guest_mask)
}

pub(super) async fn restore_signals_after_disposition<G, T>(
    guest: &mut G,
    old_mask_addr: AddrMut<'_, KernelSigset>,
) -> Result<(), Error>
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    if !reads_mask_in_place(guest.config()) {
        let old_mask: Addr<'_, KernelSigset> = old_mask_addr.into();
        let restore_signals = syscalls::RtSigprocmask::new()
            .with_how(libc::SIG_SETMASK)
            .with_set(Some(old_mask.cast()))
            .with_oldset(None)
            .with_sigsetsize(KERNEL_SIGSET_SIZE);
        guest.inject_with_retry(restore_signals).await?;
    }
    if guest.config().backend.reports_child_exit_publication
        || crate::scheduler::discarded_at_send::records(guest.config())
    {
        crate::tool_global::set_saved_guest_sigmask(guest, None).await;
    }
    Ok(())
}

async fn interrupted_child_wait_result<G, T, S>(
    guest: &mut G,
    call: S,
    disposition: WaitSignalDisposition,
) -> Result<i64, Error>
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
    S: SyscallInfo,
{
    if !guest
        .config()
        .backend
        .requires_thread_directed_process_signals
    {
        return Err(Errno::ERESTARTSYS.into());
    }
    if disposition == WaitSignalDisposition::Interrupt {
        return Err(Errno::EINTR.into());
    }

    guest.tail_inject(call).await
}

fn snapshot_process_group(pid: Pid) -> Result<libc::pid_t, Errno> {
    let pgrp = Process::new(pid.as_raw())
        .and_then(|process| process.stat())
        .map(|stat| stat.pgrp)
        .map_err(|_| Errno::ESRCH)?;
    if pgrp == 0 {
        Err(Errno::EOPNOTSUPP)
    } else {
        Ok(pgrp)
    }
}

fn guest_fd_status_flags(pid: Pid, fd: libc::c_int) -> Result<libc::c_int, Errno> {
    let path = format!("/proc/{}/fdinfo/{}", pid.as_raw(), fd);
    let contents = std::fs::read_to_string(path).map_err(|_| Errno::EBADF)?;
    let flags = contents
        .lines()
        .find_map(|line| line.strip_prefix("flags:"))
        .map(str::trim)
        .ok_or(Errno::EINVAL)?;
    libc::c_int::from_str_radix(flags, 8).map_err(|_| Errno::EINVAL)
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum FutexTimeout {
    Relative(u64),
    Absolute(LogicalTime),
}

/// Linux's `timespec64_valid`, which `futex_init_timeout` applies: a negative
/// second count or a nanosecond count outside `0..1e9` is EINVAL. Any other
/// value is valid, however large.
fn futex_timespec_is_valid(timeout: Timespec) -> bool {
    timeout.tv_sec >= 0 && (0..1_000_000_000).contains(&timeout.tv_nsec)
}

/// The largest futex timeout in nanoseconds: `timespec64_to_ktime` clamps a
/// valid timespec beyond it to `KTIME_MAX` rather than refusing it.
const FUTEX_KTIME_MAX_NANOS: u64 = i64::MAX as u64;

fn parse_futex_timeout(futex_op: i32, timeout: Timespec) -> Result<FutexTimeout, Errno> {
    if !futex_timespec_is_valid(timeout) {
        return Err(Errno::EINVAL);
    }
    let seconds = timeout.tv_sec as u64;
    let nanoseconds = timeout.tv_nsec as u64;
    // `timespec64_to_ktime`: KTIME_MAX from KTIME_SEC_MAX seconds on.
    let timeout_nanos = if seconds >= FUTEX_KTIME_MAX_NANOS / 1_000_000_000 {
        FUTEX_KTIME_MAX_NANOS
    } else {
        seconds * 1_000_000_000 + nanoseconds
    };
    // Mask off FUTEX_PRIVATE_FLAG / FUTEX_CLOCK_REALTIME before matching the
    // command: FUTEX_WAIT_BITSET measures its timeout as an *absolute* deadline,
    // whereas plain FUTEX_WAIT uses a *relative* one. A private-flagged
    // FUTEX_WAIT_BITSET (e.g. 0x89) must still be recognized as the BITSET
    // command; comparing the raw op would misclassify it as relative and add
    // the absolute deadline to the current time (leaking the epoch).
    //
    // FUTEX_LOCK_PI and FUTEX_LOCK_PI2 take absolute deadlines too
    // (`futex_init_timeout`, kernel/futex/syscalls.c:147-157 at v6.16).
    if matches!(
        futex_op & libc::FUTEX_CMD_MASK,
        libc::FUTEX_WAIT_BITSET | libc::FUTEX_LOCK_PI | libc::FUTEX_LOCK_PI2
    ) {
        Ok(FutexTimeout::Absolute(LogicalTime::from_nanos(
            timeout_nanos,
        )))
    } else {
        Ok(FutexTimeout::Relative(timeout_nanos))
    }
}

/// The clock an absolute futex deadline is measured on: CLOCK_REALTIME with
/// FUTEX_CLOCK_REALTIME, and always for FUTEX_LOCK_PI, which `do_futex` gives
/// `FLAGS_CLOCKRT` (kernel/futex/syscalls.c:114-116 at v6.16); otherwise
/// CLOCK_MONOTONIC.
fn futex_deadline_clock(futex_op: i32) -> syscalls::ClockId {
    if futex_op & libc::FUTEX_CLOCK_REALTIME != 0
        || futex_op & libc::FUTEX_CMD_MASK == libc::FUTEX_LOCK_PI
    {
        syscalls::ClockId::CLOCK_REALTIME
    } else {
        syscalls::ClockId::CLOCK_MONOTONIC
    }
}

fn rebase_absolute_timeout(
    deadline: LogicalTime,
    clock_now: LogicalTime,
    logical_now: LogicalTime,
) -> LogicalTime {
    logical_now + Duration::from_nanos(deadline.as_nanos().saturating_sub(clock_now.as_nanos()))
}

fn absolute_timeout_uses_host_clock(
    deadline: LogicalTime,
    host_clock_now: LogicalTime,
    logical_now: LogicalTime,
) -> bool {
    deadline.as_nanos().abs_diff(host_clock_now.as_nanos())
        < deadline.as_nanos().abs_diff(logical_now.as_nanos())
}

/// Where a futex wait takes its deadline from.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum FutexDeadline {
    /// The call's own timeout.
    FromCall,
    /// The deadline an interrupted timed futex wait kept for the kernel's restart
    /// (`RestartBlock`).
    Restart(Option<LogicalTime>),
}

/// How a sequentialized `sched_yield` yields to the scheduler
/// ([`sched_yield_route`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum SchedYieldRoute {
    /// A recorded chaos priority change point with a fresh random priority.
    ChaosReprioritize,
    /// A one-turn `SchedYield`, with the timeslice statistics reset.
    ReplayStrongYield,
    /// A `SchedYield` that the scheduler turns into a yield epoch.
    ChaosYieldEpoch,
    /// A `SleepUntil(0)` yield, granted at once.
    WeakYield,
    /// The end of the caller's timeslice, as at a timer expiry.
    EndTimeslice,
}

/// Choose how a sequentialized `sched_yield` yields; it reads only the
/// configuration, so a record and its replay choose alike.
///
/// - In chaos mode, thread-interleaving diversity (and thus fairness) comes
///   from re-randomizing thread priorities at preemption-timer expirations.
///   When timer preemption is disabled (`--max-timeslice disabled`),
///   priorities are fixed at thread creation and never change, so a thread
///   that spins on sched_yield while holding the numerically-lowest priority
///   would starve every thread it waits on (GH #81). There sched_yield is an
///   explicit chaos reprioritization point, recorded for chaos replay.
/// - With the timer on, chaos still redraws a priority only when a slice
///   expires, which a sched_yield loop may never reach
///   (https://github.com/rrnewton/hermit/issues/4068). There sched_yield is a
///   `SchedYield`, which the scheduler turns into a yield epoch
///   (`Scheduler::requeue_after`): the caller keeps its band, and once it has
///   passed another runnable thread over more than
///   `PLAIN_YIELDS_BEFORE_EPOCH` times it is not selected again until a thread
///   that did not yield has had a turn. It changes no
///   priority, draws nothing from the chaos PRNG and consumes no recorded
///   preemption point, so a preemption replay under `--chaos` makes the same
///   decision. A schedule replay keeps the weak yield it always had, and so
///   does a backend that does not deliver the preemption timer
///   (`BackendCapabilities::delivers_preemption_timer_events`): there a thread handed the
///   turn that never makes a syscall would never give it back.
/// - `--sched-heuristic=random` also keeps the weak yield. It draws a uniform
///   pick among the queued threads at every turn, so a yielder cannot hold
///   the CPU from the thread it waits on, and an epoch would only force the
///   yielders into near-equal shares: on the fp-reduction chaos cell
///   (https://github.com/rrnewton/hermit/issues/4150) it cut the outcomes
///   over 32 seeds to fewer than the 7 of 8 classes the cell requires.
///   `StickyRandom` keeps its pick across turns, so it keeps the epoch.
fn sched_yield_route(cfg: &Config) -> SchedYieldRoute {
    if cfg.chaos && cfg.max_timeslice.is_none() {
        SchedYieldRoute::ChaosReprioritize
    } else if !cfg.chaos && cfg.replay_preemptions_from.is_some() {
        SchedYieldRoute::ReplayStrongYield
    } else if cfg.chaos
        && cfg.replay_schedule_from.is_none()
        && cfg.backend.delivers_preemption_timer_events
        && cfg.sched_heuristic != SchedHeuristic::Random
    {
        SchedYieldRoute::ChaosYieldEpoch
    } else if cfg.chaos || cfg.replay_schedule_from.is_some() {
        SchedYieldRoute::WeakYield
    } else {
        SchedYieldRoute::EndTimeslice
    }
}

impl<T: RecordOrReplay> Detcore<T> {
    async fn futex_timeout_deadline<G: Guest<Self>>(
        &self,
        guest: &mut G,
        futex_flags: i32,
        timeout: Option<Addr<'_, Timespec>>,
    ) -> Result<Option<LogicalTime>, Error> {
        let Some(timeout) = timeout else {
            return Ok(None);
        };
        let timeout = parse_futex_timeout(futex_flags, guest.memory().read_value(timeout)?)?;
        match timeout {
            FutexTimeout::Relative(nanos) => {
                let now = thread_observe_time(guest).await;
                Ok(Some(now + Duration::from_nanos(nanos)))
            }
            FutexTimeout::Absolute(deadline)
                if self.cfg.virtualize_time
                    && !self.cfg.backend.guest_clock_reads_bypass_backend =>
            {
                Ok(Some(deadline))
            }
            FutexTimeout::Absolute(deadline) => {
                let clockid = futex_deadline_clock(futex_flags);

                let mut stack = guest.stack().await;
                let clock_output = syscalls::TimespecMutPtr(stack.reserve());
                let _stack_guard = stack.commit()?;
                let clock_call = syscalls::ClockGettime::new()
                    .with_clockid(clockid)
                    .with_tp(Some(clock_output));
                if self.cfg.virtualize_time && self.cfg.backend.guest_clock_reads_bypass_backend {
                    // Read the same live host clock as a direct guest vDSO call. Replaying a
                    // recorded value here would compare this run's host-domain deadline with the
                    // previous run's clock and turn a short timeout into an arbitrary long one.
                    guest.inject(Syscall::from(clock_call)).await?;
                } else {
                    self.record_or_replay(guest, clock_call).await?;
                }
                let clock_now = match parse_futex_timeout(
                    libc::FUTEX_WAIT_BITSET,
                    guest.memory().read_value(clock_output.0)?,
                )? {
                    FutexTimeout::Absolute(time) => time,
                    FutexTimeout::Relative(_) => unreachable!(),
                };
                let logical_now = thread_observe_time(guest).await;
                if self.cfg.virtualize_time
                    && !absolute_timeout_uses_host_clock(deadline, clock_now, logical_now)
                {
                    return Ok(Some(deadline));
                }
                Ok(Some(rebase_absolute_timeout(
                    deadline,
                    clock_now,
                    logical_now,
                )))
            }
        }
    }

    /// The deadline of a futex wait, from the call's timeout or from the record an
    /// interrupted wait kept for its restart (`FutexDeadline`).
    async fn futex_deadline<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
        deadline: FutexDeadline,
    ) -> Result<Option<LogicalTime>, Error> {
        match deadline {
            FutexDeadline::FromCall => {
                self.futex_timeout_deadline(guest, call.futex_op(), call.timeout())
                    .await
            }
            FutexDeadline::Restart(deadline) => Ok(deadline),
        }
    }

    /// Promotes the open file descriptions whose model must stay one copy
    /// (random devices and timerfds, `ThreadState::promote_shared_open_files`)
    /// before this handler's native fork, process-copying clone or exec, on a
    /// backend whose tool runs inside the guest and whose runtime routes those
    /// operations through this handler (in-guest LiteInst). DBT runs them
    /// natively and its runtime promotes there; ptrace and KVM keep the one
    /// copy outside the guest. It runs inside the caller's turn, before the
    /// operation can expose a child or a new image
    /// (<https://github.com/rrnewton/hermit/issues/4381>).
    fn promote_before_native_lifecycle<G: Guest<Self>>(&self, guest: &G) {
        let backend = &guest.config().backend;
        if self.cfg.sequentialize_threads
            && backend.promotes_open_files_before_native_lifecycle
            && !crate::syscalls::timerfd::detcore_runs_outside_the_guest(backend)
        {
            guest.thread_state().promote_shared_open_files().expect(
                "could not publish shared open file descriptions before a native fork or exec",
            );
        }
    }

    /// Before a clone that makes a process, where Detcore runs inside each
    /// guest process: the record sequences of per-process files move to
    /// Detcore's global state (`ThreadState::share_procfs_sequences`), so the
    /// copies of the tool's state the fork makes share them, as Linux's
    /// processes share the one `struct file` and `seq_file`. In-guest
    /// LiteInst does so as it promotes (`promote_before_native_lifecycle`),
    /// and DBT's runtime before its native fork; this covers SaBRe, whose
    /// runtime promotes nothing. Only with sequentialized threads, whose turns
    /// order every process's operations on the sequence.
    fn share_procfs_sequences_before_copy<G: Guest<Self>>(&self, guest: &G) {
        if self.cfg.sequentialize_threads
            && !crate::syscalls::timerfd::detcore_runs_outside_the_guest(&guest.config().backend)
        {
            guest.thread_state().share_procfs_sequences();
        }
    }

    /// Before a clone that makes a user namespace: Linux makes the caller's
    /// effective user ID the new namespace's owner (`create_user_ns`,
    /// kernel/user_namespace.c:82-136 in 6.17), and Detcore's record of user
    /// namespaces (`scheduler::user_namespaces`) takes that owner to be the
    /// real user ID every guest task has. It is, unless the caller runs, or
    /// was forked from, an image of a set-user-ID file: Detcore makes the
    /// credential-setting calls no-ops, so an exec is the one way a guest
    /// task's effective ID comes to differ from its real one, which never
    /// changes. The caller's IDs as the kernel beneath holds them (injected
    /// `getuid` and `geteuid`, read before the clone, as `create_user_ns`
    /// reads them) decide: true for a caller whose two differ, or that reads
    /// either as the overflow ID 65534 (two such IDs may still differ), or
    /// whose IDs cannot be read. Only once the clone has made the namespace is
    /// that noted, for that namespace alone
    /// (`UserNamespaces::note_owner_may_differ`), by the turn that registers
    /// the new process: a clone that fails (EINVAL for `CLONE_NEWUSER` with
    /// `CLONE_FS`; EPERM for a creator whose IDs its namespace does not map)
    /// makes no namespace and notes nothing.
    async fn user_namespace_owner_may_differ<G: Guest<Self>>(&self, guest: &mut G) -> bool {
        /// `overflowuid`'s default, which an ID the caller's user namespace
        /// does not map reads as.
        const OVERFLOW_ID: i64 = 65534;
        let uid = guest.inject(syscalls::Getuid::new()).await;
        let euid = guest.inject(syscalls::Geteuid::new()).await;
        !matches!((uid, euid), (Ok(uid), Ok(euid)) if uid == euid && uid != OVERFLOW_ID)
    }

    /// Clone, clone3, fork, vfork system calls
    pub async fn handle_clone_family<G: Guest<Self>>(
        &self,
        guest: &mut G,
        clone_family: syscalls::family::CloneFamily,
    ) -> Result<i64, Error> {
        if let syscalls::family::CloneFamily::Clone3(clone) = &clone_family
            && let Some(refusal) = self.clone3_set_tid_refusal(guest, clone).await
        {
            return refusal;
        }
        // Linux's EINVAL for the flags, on every backend, so that a backend
        // is asked only for a clone Linux would perform and declines only
        // one it cannot (`UnsupportedOperation::Clone`). A clone3's stack is
        // checked against the user address limit the backend reports, the
        // one its kernel's `access_ok` enforces (`clone3_args_einval`).
        let user_limit = matches!(clone_family, syscalls::family::CloneFamily::Clone3(_))
            .then(|| guest.user_address_limit().ok().map(|limit| limit.max_end))
            .flatten();
        if linux_refuses_clone_flags(&guest.memory(), &clone_family, user_limit) {
            return Err(Errno::EINVAL.into());
        }
        // clone3's `struct clone_args` is read field by field
        // (`clone3_field`): Reverie's whole-struct read fails for a valid
        // 64-byte one at the end of a mapping, which lost its flags, exit
        // signal and child tid address.
        let (flags, exit_signal, child_tid) = match &clone_family {
            syscalls::family::CloneFamily::Clone3(clone) => {
                let memory = guest.memory();
                (
                    clone3_field(&memory, clone, 0)
                        .map_or_else(CloneFlags::empty, CloneFlags::from_bits_truncate),
                    clone3_field(&memory, clone, 32).map_or(0, |signal| signal as libc::c_int),
                    clone3_field(&memory, clone, 16).map_or(0, |address| address as usize),
                )
            }
            syscalls::family::CloneFamily::Clone(clone) => (
                clone_family.flags(&guest.memory()),
                (clone.flags().bits() & 0xff) as libc::c_int,
                clone_family.child_tid(&guest.memory()),
            ),
            #[cfg(not(target_arch = "aarch64"))]
            _ => (
                clone_family.flags(&guest.memory()),
                libc::SIGCHLD,
                clone_family.child_tid(&guest.memory()),
            ),
        };
        let ctid = child_tid_clear_address(flags, child_tid);
        // Without sequentialized threads a sibling can run while this call
        // does, and rewrite the clone's arguments after they are read here or
        // the pidfd word before it is read back, so no pidfd is tracked then.
        let pidfd_address = guest
            .config()
            .sequentialize_threads
            .then(|| clone_pidfd_address(&clone_family, &guest.memory(), flags))
            .flatten();
        // Only a CLONE_VFORK parent waits for its child. Every backend runs a
        // forked process child concurrently with its parent and dispatches a
        // cloned thread's syscalls through this tool.
        let is_vfork = flags.contains(CloneFlags::CLONE_VFORK);

        // D41 with IR-5 (A5 step 3c.1c): the first statement of the vfork
        // branch, before `clone_flags` and `pending_vfork` are set, the
        // descriptors promoted or the signal-state copy cloned, so a vfork not
        // run leaves none of them for the death path's exit lifecycle to read.
        if is_vfork && let Some(refused) = super::helpers::kernel_run_entry_refusal(guest)? {
            return Err(refused);
        }

        // A clone that makes a user namespace makes it the caller's effective
        // user ID's (`user_namespace_owner_may_differ`): read now, noted once
        // the clone has made the namespace. Only where Detcore renders procfs
        // files, whose access checks read the record of user namespaces: not
        // under record and replay.
        let user_namespace_owner_may_differ = flags.contains(CloneFlags::CLONE_NEWUSER)
            && !flags.contains(CloneFlags::CLONE_THREAD)
            && !self.cfg.recordreplay_modes
            && self.user_namespace_owner_may_differ(guest).await;

        // The child's ID, when Detcore chooses the IDs: taken here, in this
        // turn, before the vfork parent below gives the turn up.
        let clone_plan = self
            .plan_clone_id(guest, &Syscall::from(clone_family))
            .await?;

        let ts = guest.thread_state_mut();
        assert_eq!(ts.clone_flags, None);
        assert!(ts.pending_vfork.is_none());
        ts.clone_flags = Some(flags);

        let parent_dettid = ts.dettid;
        let child_priority_entropy = if is_vfork
            && self.cfg.chaos
            && self.cfg.replay_preemptions_from.is_none()
            && self.cfg.replay_schedule_from.is_none()
        {
            let mut parent_chaos_prng = ts.chaos_prng.clone();
            Some(parent_chaos_prng.next_u64())
        } else {
            None
        };
        let blocking_child_op_id = ExternalOpId::new(parent_dettid, ts.stats.syscall_count);
        if is_vfork {
            ts.pending_vfork = Some(PendingVfork {
                parent_dettid,
                op: blocking_child_op_id,
                parent_detpid: ts.detpid.expect("detpid unset"),
                child_tid_addr: ctid,
                flags,
                exit_signal,
                child_priority_entropy,
                user_namespace_owner_may_differ,
            });
        }

        // A child's exit signal other than SIGCHLD reaches this process when
        // the child exits, at a moment set by host timing. Record it in this
        // turn, before the child exists, for every thread of the caller's
        // process, and never forget it (`Scheduler::record_host_timed_signals`).
        let exit_signals = clone_host_timed_signals(flags, exit_signal);
        if exit_signals != 0 && guest.config().backend.host_timed_signals_are_physical {
            record_host_timed_signals(guest, HostTimedSignalScope::Caller, exit_signals).await;
        }

        if !flags.contains(CloneFlags::CLONE_THREAD) {
            self.promote_before_native_lifecycle(guest);
            self.share_procfs_sequences_before_copy(guest);
        }

        // Actions shared with a new process are withdrawn from the
        // scheduler before the child exists.
        super::signal_shadow::before_clone(guest, flags.bits()).await;

        trace!("[detcore, dtid {}] parent invoking clone.", parent_dettid);

        // A CLONE_VFORK parent cannot resume until the child execs or exits.
        // Relinquish the parent's scheduler turn before entering that
        // blocking operation.
        if is_vfork && self.cfg.sequentialize_threads {
            let mut resources = Resources::new(parent_dettid);
            resources.insert(
                ResourceID::BlockingVfork(blocking_child_op_id),
                Permission::RW,
            );
            resources.fyi("clone_vfork");
            resource_request(guest, resources).await;
        }

        let call = Syscall::from(clone_family);
        let sysno = call.number();
        // A plan that leaves the kernel to number the child (or the guest
        // to choose) issues the call as main does, with `CLONE_UNTRACED`
        // cleared for a tracing backend; a chosen-ID plan issues it through
        // `inject_clone_planned`, whose staged copy clears the flag itself.
        let (maybe_res, untraced_refusal) = match clone_plan {
            super::chosen_ids::ClonePlan::Kernel | super::chosen_ids::ClonePlan::GuestChosen => {
                match inject_traced_clone(guest, clone_family, flags).await {
                    CloneInjection::Ran(result) => (result, None),
                    // No call ran. ENOMEM is what the guest gets with
                    // --allow-unsupported-syscalls: a clone Linux could not complete.
                    CloneInjection::Refused(reason) => (Err(Errno::ENOMEM), Some(reason)),
                }
            }
            _ => (
                self.inject_clone_planned(guest, call, clone_plan, is_vfork)
                    .await,
                None,
            ),
        };
        // Ask before anything else is injected: the next injection replaces
        // the backend's record.
        let refusal = if maybe_res.is_err() && untraced_refusal.is_none() {
            guest.take_unsupported_refusal()
        } else {
            None
        };

        if is_vfork && self.cfg.sequentialize_threads {
            let mut resources = Resources::new(parent_dettid);
            if maybe_res.is_err() {
                // TODO-HUMAN-REVIEW(PR-1152): Review failed deferred-vfork cancellation.
                // The scheduler cannot infer failure from the absence of a registered child: a
                // successful child may also register after this continuation. Report the known
                // injected-syscall outcome explicitly so the scheduler can cancel the barrier and
                // re-admit this parent before we propagate the original error below.
                resources.insert(
                    ResourceID::VforkFailed(blocking_child_op_id),
                    Permission::RW,
                );
                resources.fyi("clone_vfork_failed");
            } else {
                resources.insert(
                    ResourceID::BlockedExternalContinue(blocking_child_op_id),
                    Permission::RW,
                );
                resources.fyi("clone_vfork");
            }
            resource_request(guest, resources).await;
        }

        let ts = guest.thread_state_mut();
        ts.clone_flags = None; // Unset, now that it has been read by the child.
        ts.pending_vfork = None;

        // A backend that cannot create the child says so with a typed refusal
        // (an in-guest backend runs one thread of the guest; KVM cannot give a
        // child some of the sharing Linux allows). Answering the guest with
        // the refusal's errno would be an error Linux never gives a valid
        // clone, so the run is refused instead, as for an exec the backend
        // cannot perform, and named on stderr when the run ends
        // (`report_refusal_reason`).
        let source = if refusal.is_some() {
            "refused by the backend"
        } else {
            "refused"
        };
        let diagnostic = refusal
            .map(|refusal| refusal.diagnostic.to_string())
            .or(untraced_refusal);
        if let (Some(diagnostic), Err(errno)) = (diagnostic, &maybe_res) {
            let named = CloneFlags::from_bits_retain(flags.bits() & !0xff);
            crate::syscalls::helpers::report_refusal_reason(
                self.cfg.panic_on_unsupported_syscalls,
                &format!(
                    "[dtid {parent_dettid}] {sysno} {source}: {diagnostic} (flags {named:?}, \
                     exit signal {exit_signal}). No child was created."
                ),
            );
            if !self.cfg.panic_on_unsupported_syscalls {
                crate::tool_global::report_unsupported_syscall(guest, sysno).await;
            }
            return self
                .refuse_unserviceable_operation_because(guest, sysno, *errno, &diagnostic)
                .await;
        }

        let res = maybe_res?;

        if !flags.contains(CloneFlags::CLONE_THREAD) {
            // Only a successful process clone can let another process mutate
            // inherited open file descriptions. Failed clone-family calls leave
            // the previously observed flock state authoritative.
            guest.thread_state().forget_flock_modes();
        }

        // Match ordinary clone: the parent consumes the priority entropy after
        // the child has inherited the parent state.
        if is_vfork
            && self.cfg.chaos
            && self.cfg.replay_preemptions_from.is_none()
            && self.cfg.replay_schedule_from.is_none()
        {
            let _ = guest
                .thread_state_mut()
                .chaos_prng_next_u64("child_priority");
        }

        let child_tid = Pid::from_raw(res as i32);
        let child_dettid = DetTid::from_raw(child_tid.into()); // TODO(T78538674), virtualized tid/pid
        trace!(
            "[detcore] dtid {} cloned, continuing parent + register new thread.",
            child_dettid
        );

        if !is_vfork {
            create_child_thread(guest, child_dettid, ctid, Some(flags), exit_signal, None).await;
            // The clone made the namespace: note its owner, in the turn that
            // registered the child (a vfork child notes its own at its
            // registration, `Detcore::handle_thread_start`).
            if user_namespace_owner_may_differ {
                crate::tool_global::note_user_namespace_owner_may_differ(guest, child_dettid).await;
            }
        }

        if let Some(address) = pidfd_address {
            self.register_clone_pidfd(guest, address, child_dettid)
                .await;
        }

        {
            // The child will have updated their pedigree, we update ours before continuing.
            let parent_pedigree = &mut guest.thread_state_mut().pedigree;
            let child_pedigree = parent_pedigree.fork_mut();
            debug!(
                "[dtid {}] after creating child thread (tid {}, pedigree {}) parents pedigree becomes {}",
                parent_dettid, child_dettid, child_pedigree, parent_pedigree,
            );
        }

        // A nested creator sees its child's pid in its own PID namespace, as
        // the kernel returned it; Reverie reports the container's
        // (https://github.com/rrnewton/hermit/issues/4090).
        if guest.thread_state().nested_pid_namespace {
            let refusal = match crate::tool_global::local_pid(guest, child_dettid).await {
                Ok(Some(local)) => return Ok(local as i64),
                Ok(None) => {
                    format!("child {child_dettid} has no pid recorded in its creator's namespace")
                }
                Err(reason) => reason,
            };
            tracing::error!(
                "[detcore, dtid {}] the pid a clone in a nested PID namespace returns cannot be translated: {} (https://github.com/rrnewton/hermit/issues/4090)",
                parent_dettid,
                refusal,
            );
            return self
                .refuse_unserviceable_operation(
                    guest,
                    reverie::syscalls::Sysno::clone,
                    Errno::ENOSYS,
                )
                .await;
        }
        Ok(child_dettid.as_raw() as i64)
    }

    // TODO-HUMAN-REVIEW(PR-2985): Review scheduler tracking of set_tid_address.
    /// `set_tid_address` system call.
    ///
    /// Linux owns the guest-visible registration and return value. Detcore
    /// mirrors the accepted address into the scheduler so its modeled
    /// CHILD_CLEARTID wake targets the same word as the backend.
    pub async fn handle_set_tid_address<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::SetTidAddress,
    ) -> Result<i64, Error> {
        let address = call.tidptr().map_or(0, |pointer| pointer.as_raw());
        crate::reserved_input::expose_local_overlap(
            guest,
            address as u64,
            4,
            "clear-tid-reserved-reference",
        )?;
        let result = self
            .record_or_replay(guest, Syscall::SetTidAddress(call))
            .await?;
        if guest.config().sequentialize_threads {
            set_child_tid_address(guest, address).await;
        }
        trace!(
            "[detcore, dtid {}] child TID clear address registered: {address:#x}",
            guest.thread_state().dettid,
        );
        Ok(result)
    }

    /// `set_robust_list` system call.
    ///
    /// Still a pass-through: Linux owns the registration and supplies the
    /// result, and Detcore only records the head address so it can replay
    /// `exit_robust_list()` when the thread dies (see
    /// `Self::run_robust_list_owner_death`). Recording happens only after the
    /// kernel accepts the call, so a rejected length or address never becomes
    /// Detcore state.
    ///
    /// The call goes through `record_or_replay`, like every other pass-through.
    /// Using `Guest::inject` directly would keep the classification but drop the
    /// behavior it implies: the syscall would vanish from a `hermit record`
    /// trace, and a log recorded by a build that did record it would no longer
    /// replay.
    // AUTONOMOUS-BOT-IMPLEMENTED
    pub async fn handle_set_robust_list<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::SetRobustList,
    ) -> Result<i64, Error> {
        let head = call.head().map(AddrMut::as_raw);
        let len = call.len();
        if let Some(head) = head {
            crate::reserved_input::expose_local_overlap(
                guest,
                head as u64,
                len as u64,
                "robust-list-reserved-reference",
            )?;
        }
        let res = self
            .record_or_replay(guest, Syscall::SetRobustList(call))
            .await?;
        // TODO-HUMAN-REVIEW(PR-2223): Review robust-list
        // head tracking used to drive owner-death wakeups.
        let recorded = match head {
            // `set_robust_list(NULL, ...)` unregisters the list.
            None => None,
            // Fail closed, and not dead code: `len` is the guest's own argument,
            // so a 32-bit guest (or a bug) can present the 12-byte
            // `compat_robust_list_head`, whose fields sit at different offsets.
            // The 64-bit walk would misread it, so refuse to record it at all
            // rather than walk a layout we cannot parse.
            Some(_) if len != robust_list::ROBUST_LIST_HEAD_LEN => None,
            Some(addr) => Some(addr),
        };
        guest.thread_state_mut().record_robust_list_head(recorded);
        trace!(
            "[detcore, dtid {}] robust-list head registered: {:?}",
            guest.thread_state().dettid,
            recorded,
        );
        Ok(res)
    }

    /// Replay Linux's `exit_robust_list()` for the calling thread.
    ///
    /// Linux runs this from `mm_release()` while a task dies. Detcore performs
    /// the same walk and issues the wake against its own modeled waiter pool,
    /// which is where precise-mode futex waiters actually live. Ptrace leaves
    /// the atomic word transition to Linux on every backend that enters this
    /// path ([`OwnerDeathPath`]), and the wake reaches a waiter only after
    /// Linux has made it. The algorithm is in
    /// [`crate::syscalls::robust_list`]; this function only supplies guest
    /// memory and the scheduler wake.
    ///
    /// Only the precise futex model needs this. Polling and external modes park
    /// waiters in the host kernel, which performs its own robust-list cleanup;
    /// and without thread sequentialization Detcore does not model futexes at
    /// all.
    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(PR-2223): Review owner-death wakeup
    // emulation, which changes how a dying thread's peers are scheduled.
    async fn run_robust_list_owner_death<G: Guest<Self>>(&self, guest: &mut G) {
        let Some(path) = self.robust_owner_death_path() else {
            return;
        };
        let Some(head) = guest.thread_state().robust_list_head else {
            return;
        };
        let dettid = guest.thread_state().dettid;
        // Which TID goes in the comparison? Not one Detcore hands out: `gettid`
        // is a reviewed pass-through, and glibc puts the value the kernel
        // supplied through `CLONE_PARENT_SETTID` into the lock word, not a
        // `gettid` result. The comparison is valid for a narrower reason —
        // `DetTid` currently *is* the raw namespaced `Tid`. `init_thread_state`
        // builds every one with `DetPid::from_raw(tid.into())` (detcore/src/lib.rs,
        // `lib.rs:1257` at this commit), four lines under
        // `// TODO(T78538674): virtualize tid, extend tid<=>dettid mapping here.`
        // Completing that TODO breaks this comparison, which would then have to
        // map back to the guest-visible TID.
        // `hermit-cli/tests/robust_futex_owner_death.rs` is the tripwire: it
        // fails the moment the two diverge.
        let owner_tid = dettid.as_raw() as u32;

        let mut marked = HashMap::new();
        let mut effects = GuestRobustEffects::<'_, G, T> {
            guest,
            dettid,
            staged_wakes: None,
            marked: &mut marked,
            tool: PhantomData,
        };
        let outcome = robust_list::exit_robust_list(&mut effects, head, owner_tid).await;
        if path == OwnerDeathPath::Barrier {
            guest.thread_state().mark_robust_list_walked_by_tool();
        }
        if outcome.head_unreadable {
            trace!(
                "[detcore, dtid {}] unreadable robust-list head at {:#x}; no owner-death wakeups",
                dettid, head,
            );
        } else if outcome.aborted || outcome.next_faulted || outcome.truncated {
            trace!(
                "[detcore, dtid {}] robust-list walk stopped early after {} entr(ies): {:?}",
                dettid, outcome.entries_visited, outcome,
            );
        }
    }

    /// Read every registered robust list in the current thread group while
    /// its address space still exists, but hold its modeled wakes until the
    /// corresponding exit callback. On ptrace that callback confirms Linux has
    /// completed the atomic owner-word update.
    ///
    /// On [`OwnerDeathPath::Barrier`] nothing is staged. An exit_group walks
    /// the words and wakes their waiters at once instead
    /// (`Self::handle_exit_group`), and no waiter runs before the kernel has
    /// ended the group. A delivered signal
    /// may still be caught or ignored: Detcore must not mark a live owner's
    /// word, and that backend's native exit callback cannot tell which signal
    /// ended the thread group.
    pub(crate) async fn stage_thread_group_robust_list_wakes<G: Guest<Self>>(
        &self,
        guest: &mut G,
        reason: RobustListExit,
    ) {
        match self.robust_owner_death_path() {
            None | Some(OwnerDeathPath::Barrier) => {}
            Some(OwnerDeathPath::Kernel) => {
                let staged = self
                    .read_thread_group_robust_list_wakes(guest, OwnerDeath::Exit)
                    .await;
                guest.thread_state().stage_robust_list_wakes(reason, staged);
            }
        }
    }

    /// Replay Linux's `exit_robust_list()` for each `(owner, head)` of the
    /// current thread group, in owner order, as that owner's list, waking at
    /// once ([`OwnerDeathPath::Barrier`]). The threads the grant killed have not made
    /// their native exits (`ThreadState::wait_for_exit_group_robust_walk`), so
    /// every word reads as the guest left it.
    async fn run_thread_group_robust_list_owner_death<G: Guest<Self>>(
        &self,
        guest: &mut G,
        heads: Vec<RobustListOwner>,
    ) {
        // One group exit: a word Linux marks under one owner reads as marked
        // under every later one.
        let mut marked = HashMap::new();
        for RobustListOwner {
            dettid: owner,
            head,
        } in heads
        {
            let mut effects = GuestRobustEffects::<'_, G, T> {
                guest,
                dettid: owner,
                staged_wakes: None,
                marked: &mut marked,
                tool: PhantomData,
            };
            let outcome =
                robust_list::exit_robust_list(&mut effects, head, owner.as_raw() as u32).await;
            if outcome.head_unreadable || outcome.aborted {
                trace!(
                    "[detcore, dtid {}] robust-list owner death stopped early: {:?}",
                    owner, outcome,
                );
            }
        }
    }

    /// How this backend orders owner-death wakes after Linux's walk, or `None`
    /// where Detcore does not model robust-futex owner death.
    ///
    /// Only the precise futex model needs owner death modeled. Polling and
    /// external modes park waiters in the host kernel, which performs its own
    /// robust-list cleanup; and without thread sequentialization Detcore does
    /// not model futexes at all.
    fn robust_owner_death_path(&self) -> Option<OwnerDeathPath> {
        owner_death_path(&self.cfg)
    }

    /// Before the send of SIGKILL reservation `token`, record the robust list
    /// of every thread the send kills (`Scheduler::sigkill_dying_threads`),
    /// for its exit callback to walk ([`Self::sigkill_robust_list_wakes`]).
    ///
    /// Linux walks a dying thread's robust list in its own exit, before its
    /// address space goes away (`exit_mm_release`, `futex_exit_release`,
    /// `exit_robust_list`), however the thread dies. A SIGKILL leaves no stop
    /// at which Detcore could read the list, and the exit callback comes after
    /// the address space is gone, so the sender reads it here, in its own turn.
    /// Nothing changes the list between this read and Linux's walk: the
    /// victims run no guest code again, and no other guest thread takes a turn
    /// before the send. Only the backends whose exit callback follows Linux's
    /// walk need it ([`OwnerDeathPath::Kernel`]), and those run Detcore in the
    /// tracer, which may read every guest's memory.
    pub(crate) async fn record_sigkill_robust_lists<G: Guest<Self>>(
        &self,
        guest: &mut G,
        token: u64,
    ) {
        if self.robust_owner_death_path() != Some(OwnerDeathPath::Kernel) {
            return;
        }
        let mut lists = Vec::new();
        for (tid, mm) in crate::tool_global::sigkill_dying_threads(guest, token).await {
            if let Some(list) = robust_list::record_robust_list(tid.as_raw()).await {
                lists.push((tid, mm, list));
            }
        }
        if !lists.is_empty() {
            crate::tool_global::record_sigkill_robust_lists(guest, token, lists).await;
        }
    }

    /// In the exit callback of a thread a SIGKILL ended, replay Linux's
    /// `exit_robust_list` over the list the SIGKILL's sender recorded for it
    /// ([`Self::record_sigkill_robust_lists`]) and deliver its wakes: one
    /// waiter per futex Linux marked `FUTEX_OWNER_DIED` with `FUTEX_WAITERS`
    /// set, and one per pending word that held no owner. Linux has made every
    /// owner-word transition by now, as for the other exits on this path. A
    /// victim's wakes are held until every victim of the send is accounted and
    /// then run in victim order (`Scheduler::retain_sigkill_victim_wakes`); the
    /// sender of a send that ended its own process still holds its `Exit`
    /// grant, so its wakes run at once, before any other thread takes a turn.
    pub(crate) async fn sigkill_robust_list_wakes<R: GlobalRPC<GlobalState>>(
        &self,
        global_state: &R,
        thread_state: &ThreadState<T::ThreadState>,
        exit_signal: Option<i32>,
    ) {
        if exit_signal != Some(libc::SIGKILL)
            || self.robust_owner_death_path() != Some(OwnerDeathPath::Kernel)
            // A list staged for this exit is delivered by the staged path.
            || thread_state.has_matching_robust_list_exit(exit_signal)
        {
            return;
        }
        let time = thread_state.thread_logical_time.clone();
        let mm = thread_state.mm_id;
        let Some(list) =
            crate::tool_global::take_sigkill_robust_list(time.clone(), global_state, mm).await
        else {
            return;
        };
        let dettid = thread_state.dettid;
        // The owner word holds the TID the kernel gave the thread, which is the
        // raw `DetTid` (see `Self::run_robust_list_owner_death`).
        let (futexes, outcome) =
            robust_list::owner_death_wakes_in_snapshot(&list, dettid.as_raw() as u32, |address| {
                thread_state.futex_id(address, false)
            })
            .await;
        if outcome.head_unreadable || outcome.aborted || outcome.next_faulted || outcome.truncated {
            trace!(
                "[detcore, dtid {}] SIGKILLed thread's robust-list walk stopped early: {:?}",
                dettid, outcome,
            );
        }
        let wakes: Vec<(DetTid, RobustListWake)> = futexes
            .into_iter()
            .map(|futex| (dettid, RobustListWake { futex }))
            .collect();
        let identities: Vec<FutexID> = wakes.iter().map(|(_, wake)| wake.futex).collect();
        let counts =
            crate::tool_global::robust_list_wakes_after_exit(time, global_state, mm, wakes).await;
        // A held batch is answered with no counts and logged when it runs.
        for (futex, count) in identities.into_iter().zip(counts) {
            info!(
                "[detcore, dtid {}] robust-list owner death woke {} waiter(s) on futex {:?} after physical exit",
                dettid, count, futex,
            );
        }
    }

    /// The owner-death wakes a successful execve makes Linux deliver, in
    /// delivery order, for a backend that runs the native execve outside
    /// Detcore's handler and so cannot stage them in this thread's state (DBT,
    /// whose new image starts a fresh runtime). Read while the old image is
    /// mapped, before the native exec; none where Detcore does not model
    /// owner death (<https://github.com/rrnewton/hermit/issues/4268>).
    pub async fn exec_robust_list_wakes<G: Guest<Self>>(
        &self,
        guest: &mut G,
    ) -> Vec<(DetTid, FutexID)> {
        if self.robust_owner_death_path().is_none() {
            return Vec::new();
        }
        let wakes = self
            .read_thread_group_robust_list_wakes(guest, OwnerDeath::Exec)
            .await;
        crate::tool_local::flatten_exec_robust_list_wakes(wakes)
            .into_iter()
            .map(|(owner, wake)| (owner, wake.futex))
            .collect()
    }

    /// The owner-death wakes Linux's `exit_robust_list` would make for every
    /// registered robust list in the current thread group, read without
    /// changing guest memory: Linux makes the owner-word transitions. Callers
    /// decide whether Detcore models owner death at all
    /// ([`Self::robust_owner_death_path`]).
    ///
    /// Each list is walked as its owner's, with that owner's TID, except the
    /// caller's own list in an exec by a thread that is not the group leader.
    /// `de_thread` gives that caller the leader's TID (`exchange_tids`) before
    /// `exec_mm_release` walks its list, so `handle_futex_death` compares the
    /// owner words with the thread group ID and leaves a word the caller owns
    /// under its old TID alone (fs/exec.c, kernel/futex/core.c).
    async fn read_thread_group_robust_list_wakes<G: Guest<Self>>(
        &self,
        guest: &mut G,
        death: OwnerDeath,
    ) -> Vec<(DetTid, Vec<RobustListWake>)> {
        let caller = guest.thread_state().dettid;
        let tgid = guest.thread_state().detpid.expect("detpid unset");
        // A thread whose own exit Detcore already walked (its head stays
        // registered while an exit_group is filed) is left out, as an
        // exit_group's walk leaves it out, so no list is walked twice (Claude
        // review of https://github.com/rrnewton/hermit/pull/4352, F4).
        let mut heads: Vec<(DetTid, usize)> = guest
            .thread_state()
            .robust_list_owners_for_exit_group()
            .into_iter()
            .map(|owner| (owner.dettid, owner.head))
            .collect();
        if death == OwnerDeath::Exec {
            // de_thread waits until every other thread has exited, each walking
            // its own list, before exec_mm_release walks the caller's; with
            // marks carried across lists, the caller's must come last (Claude
            // review of https://github.com/rrnewton/hermit/pull/4277 at
            // 65138a17, N5).
            heads.sort_by_key(|(owner, _)| *owner == caller);
        }
        let mut staged = Vec::with_capacity(heads.len());
        let mut marked = HashMap::new();
        for (owner, head) in heads {
            let walked_as = if death == OwnerDeath::Exec && owner == caller {
                tgid.as_raw()
            } else {
                owner.as_raw()
            };
            let mut wakes = Vec::new();
            let mut effects = GuestRobustEffects::<'_, G, T> {
                guest,
                dettid: owner,
                staged_wakes: Some(&mut wakes),
                marked: &mut marked,
                tool: PhantomData,
            };
            let outcome = robust_list::exit_robust_list(&mut effects, head, walked_as as u32).await;
            if outcome.head_unreadable || outcome.aborted {
                trace!(
                    "[detcore, dtid {}] could not stage complete robust-list owner-death effects: {:?}",
                    owner, outcome,
                );
            }
            staged.push((owner, wakes));
        }
        staged
    }

    /// Exit system call
    pub async fn handle_exit<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Exit,
    ) -> Result<i64, Error> {
        // This thread may be its process's last (`crate::guest_log`).
        crate::guest_log::flush_unsent();
        // A raw `exit` of a process's last thread ends the process as an
        // `exit_group` does, and the scheduler then sends the parent's SIGCHLD
        // with Linux's siginfo, as for `handle_exit_group`. Only the exit grant
        // knows whether this thread is the last, so every raw exit reports its
        // status, kept for this thread alone until that grant settles it.
        if self.cfg.backend.reports_kernel_child_exit_signals {
            let uid = real_uid(guest.tid().as_raw()).unwrap_or_else(|| unsafe { libc::getuid() });
            crate::tool_global::child_exit_sigchld(
                guest,
                crate::scheduler::child_exit_sigchld::ChildExitSigchldControl::RawExitStatus {
                    code: libc::CLD_EXITED,
                    status: call.status() & 0xff,
                    uid,
                },
            )
            .await;
        }
        let request = guest.thread_state().mk_request(
            ResourceID::Exit {
                group: false,
                process: guest.thread_state().detpid.expect("detpid unset"),
                mm: guest.thread_state().mm_id,
            },
            Permission::RW,
        );
        resource_request(guest, request).await;
        self.run_robust_list_owner_death(guest).await;
        // A leader whose group lives on is a zombie from here until its last
        // sibling leaves, and its backend reports its exit only then: it
        // leaves the scheduler now, after its last request
        // (https://github.com/rrnewton/hermit/issues/4100).
        let state = guest.thread_state();
        if self.cfg.sequentialize_threads
            && state
                .detpid
                .is_some_and(|pid| pid.as_raw() == state.dettid.as_raw())
            && crate::tool_global::retire_exited_leader(guest).await
            && self.cfg.replay_data.is_some()
        {
            // The recorder reads the process's descriptor table through its
            // leader, which is a zombie from here, so it would record the
            // group's later output as ordinary writes that replay drops
            // (https://github.com/rrnewton/hermit/issues/4244).
            let message = format!(
                "hermit: thread-group leader {} exited while its threads run on, which record \
                 and replay cannot yet capture, so the run is refused \
                 (https://github.com/rrnewton/hermit/issues/4244)",
                guest.thread_state().dettid
            );
            tracing::error!("{message}");
            let _ = std::io::Write::write_fmt(
                &mut crate::util::RetryingStderr,
                format_args!("{message}\n"),
            );
            crate::tool_global::unrecoverable_shutdown(
                guest,
                detcore_model::HERMIT_POLICY_REFUSAL_EXIT,
            )
            .await;
        }
        // A table's last holder takes it with its exit: after the grant, just
        // before the native exit, as an exit_group does
        // (`Self::release_table_at_exit`).
        self.release_table_at_exit(guest, false).await;
        // It's ok here that we skip running the posthook:
        guest.tail_inject(call).await
    }

    /// Exit_group system call
    pub async fn handle_exit_group<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::ExitGroup,
    ) -> Result<i64, Error> {
        crate::reserved_input::before_exit_group(guest)?;
        // One of the last points where this process's unsent warnings can
        // still be reported (`crate::guest_log`).
        crate::guest_log::flush_unsent();
        // Where the kernel also notifies the parent, the scheduler sends the
        // parent's SIGCHLD itself and gives it the siginfo Linux would
        // (`scheduler::child_exit_sigchld`): CLD_EXITED and the exit code.
        if self.cfg.backend.reports_kernel_child_exit_signals {
            let uid = real_uid(guest.tid().as_raw()).unwrap_or_else(|| unsafe { libc::getuid() });
            crate::tool_global::child_exit_sigchld(
                guest,
                crate::scheduler::child_exit_sigchld::ChildExitSigchldControl::ExitStatus {
                    code: libc::CLD_EXITED,
                    status: call.status() & 0xff,
                    uid,
                },
            )
            .await;
        }
        // On [`OwnerDeathPath::Barrier`] the walk follows the grant and wakes
        // at once, as an exit does (`Self::run_robust_list_owner_death`):
        // nothing can call the exit_group off, the grant logically kills the
        // group's other threads, so none of them runs guest code again, and
        // the scheduler commits no turn until the kernel has ended every
        // thread of the group, so no waiter runs before Linux has marked its
        // word. Holding the wakes for the exit callbacks would lose them on
        // DBT, which answers a logically killed thread's callback
        // `ThreadExited`. Read the registrations at the grant, as Linux's
        // walks use the ones current when each thread dies. Filing first keeps
        // an exiting thread's head registered until then and holds the killed
        // threads' native exits until the walk is done
        // (`ThreadState::file_exit_group_for_robust_lists`,
        // `ThreadState::wait_for_exit_group_robust_walk`): a killed thread's
        // native exit would otherwise let Linux mark and clear its words before
        // the walk reads them. The lists stay mapped until the native
        // exit_group.
        let barrier = self.robust_owner_death_path() == Some(OwnerDeathPath::Barrier);
        if barrier {
            guest.thread_state().file_exit_group_for_robust_lists();
        }
        let request = guest.thread_state().mk_request(
            ResourceID::Exit {
                group: true,
                process: guest.thread_state().detpid.expect("detpid unset"),
                mm: guest.thread_state().mm_id,
            },
            Permission::RW,
        );
        resource_request(guest, request).await;
        if barrier {
            guest.thread_state().begin_exit_group_robust_walk();
            let owners = guest.thread_state().robust_list_owners_for_exit_group();
            self.run_thread_group_robust_list_owner_death(guest, owners)
                .await;
            guest.thread_state().finish_exit_group_robust_walk();
        } else {
            self.stage_thread_group_robust_list_wakes(guest, RobustListExit::ExitGroup)
                .await
        }
        // Every thread of the process exits with it: a table only they held
        // goes with this exit, once the grant has logically ended the other
        // threads, so none of them runs again against a table Detcore has let
        // go, and before the native exit_group, so no turn runs between
        // (`Self::release_table_at_exit`).
        self.release_table_at_exit(guest, true).await;
        // It's ok here that we skip running the posthook:
        guest.tail_inject(call).await
    }

    /// On DBT, end the thread group in the schedule before a signal that
    /// ends it by default is delivered natively
    /// (<https://github.com/rrnewton/hermit/issues/4278>). DynamoRIO carries
    /// out such a default action itself, and before the process exits it
    /// synchronizes with every other thread of it. A thread waiting for its
    /// turn is blocked in the client's call to the coordinator, inside a
    /// DynamoRIO event callback, where DynamoRIO cannot suspend it, so the
    /// dying thread waited for it forever. The `Exit` grant of an exit_group
    /// logically kills the group's other threads and cancels their pending
    /// requests, so each returns from its callback and can be synchronized;
    /// the robust lists are walked as an exit_group's are. Returns whether it
    /// ended the group.
    ///
    /// The decision is the action read in this thread's `InboundSignal` turn.
    /// Linux commits it under the signal lock: for an unblocked signal,
    /// `complete_signal` sets `SIGNAL_GROUP_EXIT` and queues SIGKILL to every
    /// other thread of the group, so no sibling runs another user instruction
    /// after the decision. Filing the `Exit` request ends this thread's turn,
    /// so the thread first asks that the request be granted at the very next
    /// turn (`Scheduler::hold_turn_for_group_exit`). No sibling takes a turn
    /// between the decision and the grant, which logically kills the siblings,
    /// so none runs guest code before the native delivery (Claude re-check of
    /// https://github.com/rrnewton/hermit/pull/4387).
    ///
    /// Should a sibling still run first, its action change must not undo the
    /// decision. DynamoRIO reads the action again when it delivers, so after
    /// the grant the action is read again and, if a sibling changed it, set
    /// back to `SIG_DFL` in this dying process, and the delivery carries out
    /// the committed decision (Codex review of
    /// https://github.com/rrnewton/hermit/pull/4387, P1).
    ///
    /// The gate is this backend's: DynamoRIO carries out a default action in
    /// the process and synchronizes every thread before it exits. Today only
    /// DBT sends process signals to a named thread
    /// (`requires_thread_directed_process_signals`), so that flag selects it.
    pub(crate) async fn end_thread_group_before_fatal_delivery<G: Guest<Self>>(
        &self,
        guest: &mut G,
        signal: SigWrapper,
    ) -> bool {
        if !(self.cfg.sequentialize_threads
            && self.cfg.backend.requires_thread_directed_process_signals)
            || !signal_default_action_ends_the_process(signal)
        {
            return false;
        }
        match self.signal_is_left_at_default(guest, signal).await {
            Ok(true) => {}
            Ok(false) => return false,
            Err(error) => {
                tracing::warn!(
                    "[detcore, dtid {}] cannot read the disposition of {}: {}",
                    guest.thread_state().dettid,
                    signal,
                    error
                );
                return false;
            }
        }
        info!(
            "[detcore, dtid {}] {} ends its thread group by default",
            guest.thread_state().dettid,
            signal
        );
        let barrier = self.robust_owner_death_path() == Some(OwnerDeathPath::Barrier);
        if barrier {
            guest.thread_state().file_exit_group_for_robust_lists();
        }
        let dettid = guest.thread_state().dettid;
        if !hold_turn_for_group_exit(guest, dettid).await {
            tracing::warn!(
                "[detcore, dtid {}] the scheduler did not hold the turn for the group exit of {}",
                dettid,
                signal
            );
        }
        let request = guest.thread_state().mk_request(
            ResourceID::Exit {
                group: true,
                process: guest.thread_state().detpid.expect("detpid unset"),
                mm: guest.thread_state().mm_id,
            },
            Permission::RW,
        );
        resource_request(guest, request).await;
        match self.signal_is_left_at_default(guest, signal).await {
            Ok(true) => {}
            changed => {
                info!(
                    "[detcore, dtid {}] the action for {} changed after the delivery decision \
                     ({:?}); restoring SIG_DFL in the dying process",
                    guest.thread_state().dettid,
                    signal,
                    changed.map(|default| !default)
                );
                if let Err(error) = self.restore_default_action(guest, signal).await {
                    tracing::warn!(
                        "[detcore, dtid {}] cannot restore SIG_DFL for {}: {}",
                        guest.thread_state().dettid,
                        signal,
                        error
                    );
                }
            }
        }
        if barrier {
            guest.thread_state().begin_exit_group_robust_walk();
            let owners = guest.thread_state().robust_list_owners_for_exit_group();
            self.run_thread_group_robust_list_owner_death(guest, owners)
                .await;
            guest.thread_state().finish_exit_group_robust_walk();
        }
        true
    }

    /// Set the guest's action for `signal` to `SIG_DFL`.
    async fn restore_default_action<G: Guest<Self>>(
        &self,
        guest: &mut G,
        signal: SigWrapper,
    ) -> Result<(), Error> {
        let default = KernelSigaction {
            handler: libc::SIG_DFL as u64,
            flags: 0,
            restorer: 0,
            mask: 0,
        };
        let mut stack = guest.stack().await;
        let action_addr = stack.push(default);
        let _guard = stack.commit()?;
        let call = syscalls::RtSigaction::new()
            .with_signum(signal.raw())
            .with_action(Some(action_addr.cast()))
            .with_old_action(None)
            .with_sigsetsize(std::mem::size_of::<u64>());
        guest.inject_with_retry(call).await?;
        // Detcore's own change, which the signal-state copy does not record:
        // the copy, and the actions it shares, are unknown now.
        super::signal_shadow::give_up(
            guest,
            "Detcore reset an action to the default before a fatal delivery",
        );
        Ok(())
    }

    /// Whether the guest's action for `signal` is the default (`SIG_DFL`),
    /// as the backend reports it to the guest.
    async fn signal_is_left_at_default<G: Guest<Self>>(
        &self,
        guest: &mut G,
        signal: SigWrapper,
    ) -> Result<bool, Error> {
        let mut stack = guest.stack().await;
        let action_addr = stack.reserve::<KernelSigaction>();
        let _guard = stack.commit()?;
        let call = syscalls::RtSigaction::new()
            .with_signum(signal.raw())
            .with_action(None)
            .with_old_action(Some(action_addr.cast()))
            .with_sigsetsize(std::mem::size_of::<u64>());
        guest.inject_with_retry(call).await?;
        let action: KernelSigaction = guest.memory().read_value(action_addr)?;
        Ok(action.handler == libc::SIG_DFL as u64)
    }

    /// Futex system call, which can block.
    pub async fn handle_futex<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
    ) -> Result<i64, Error> {
        self.handle_futex_from(guest, call, FutexDeadline::FromCall)
            .await
    }

    /// `handle_futex`, taking a wait's deadline from `deadline`. A `restart_syscall`
    /// resumes an interrupted timed futex wait here with the deadline it kept,
    /// and the value is compared again, as in Linux's `futex_wait_restart`
    /// (`Detcore::handle_restart_syscall`).
    pub(crate) async fn handle_futex_from<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
        deadline: FutexDeadline,
    ) -> Result<i64, Error> {
        let dettid = guest.thread_state().dettid;
        // Detcore emulates the futex commands below, so it also answers, as Linux's
        // `do_futex` (kernel/futex/syscalls.c) does, for the ones it does not serve:
        // before the futex address is even looked at.
        if self.cfg.sequentialize_threads
            && !matches!(self.cfg.debug_futex_mode, BlockingMode::External)
        {
            match classify_futex_command(call.futex_op()) {
                FutexCommand::Served => {}
                FutexCommand::NoSys => return Err(Error::Errno(Errno::ENOSYS)),
                FutexCommand::RequeuePi(name) => {
                    return self
                        .refuse_futex_command(
                            guest,
                            name,
                            "Detcore does not emulate requeue-PI futexes (PI condition variables)",
                        )
                        .await;
                }
            }
        }
        // FUTEX_REQUEUE, FUTEX_CMP_REQUEUE and FUTEX_WAKE_OP key their words
        // without reading `uaddr` (only CMP_REQUEUE compares it), and NULL is a
        // valid private key for them, so they take their own path before the
        // NULL passthrough and the read below.
        if self.cfg.sequentialize_threads
            && !matches!(self.cfg.debug_futex_mode, BlockingMode::External)
        {
            let command = call.futex_op() & libc::FUTEX_CMD_MASK;
            // The priority-inheritance lock commands read and write their word
            // themselves, NULL included (EFAULT), and park on the precise
            // model's waiter pool, which polling mode does not keep.
            if let Some(name) = pi_lock_command_name(command) {
                if matches!(self.cfg.debug_futex_mode, BlockingMode::Polling) {
                    return self
                        .refuse_futex_command(guest, name, POLLING_REFUSAL)
                        .await;
                }
                // AUTONOMOUS-BOT-IMPLEMENTED
                return if command == libc::FUTEX_UNLOCK_PI {
                    self.handle_futex_unlock_pi(guest, call).await
                } else {
                    self.handle_futex_lock_pi(guest, call, command).await
                };
            }
            // FUTEX_WAKE and FUTEX_WAKE_BITSET only key their word too, and a
            // requeue can leave a modeled waiter on any admitted private key,
            // NULL or unmapped included, which a wake must still reach.
            if matches!(command, libc::FUTEX_WAKE | libc::FUTEX_WAKE_BITSET)
                && matches!(self.cfg.debug_futex_mode, BlockingMode::Precise)
            {
                return self.handle_futex_wake(guest, call, command).await;
            }
            let name = match command {
                libc::FUTEX_REQUEUE => Some("FUTEX_REQUEUE"),
                libc::FUTEX_CMP_REQUEUE => Some("FUTEX_CMP_REQUEUE"),
                libc::FUTEX_WAKE_OP => Some("FUTEX_WAKE_OP"),
                _ => None,
            };
            if let Some(name) = name {
                // Polling waiters are not on a waiter list that a requeue or a
                // WAKE_OP's second wake could act on.
                if matches!(self.cfg.debug_futex_mode, BlockingMode::Polling) {
                    return self
                        .refuse_futex_command(guest, name, POLLING_REFUSAL)
                        .await;
                }
                return if command == libc::FUTEX_WAKE_OP {
                    // AUTONOMOUS-BOT-IMPLEMENTED
                    self.handle_futex_wake_op(guest, call).await
                } else {
                    // AUTONOMOUS-BOT-IMPLEMENTED
                    self.handle_futex_requeue(guest, call, command).await
                };
            }
        }
        let ptr = match call.uaddr() {
            None => {
                // null pointer error:
                return Ok(guest.inject(call).await?);
            }
            Some(x) => x,
        };
        if self.cfg.sequentialize_threads
            && !matches!(self.cfg.debug_futex_mode, BlockingMode::External)
            && !AddrMut::as_raw(ptr).is_multiple_of(std::mem::size_of::<u32>())
        {
            // `get_futex_key` refuses a misaligned futex word before any access.
            return Err(Error::Errno(Errno::EINVAL));
        }
        if !self.cfg.sequentialize_threads {
            return crate::syscalls::helpers::inject_keeping_kernel_restart(guest, call).await;
        }
        let polling = match self.cfg.debug_futex_mode {
            BlockingMode::External => {
                return self.record_or_replay_blocking(guest, call.into()).await;
            }
            BlockingMode::Precise => false,
            BlockingMode::Polling => true,
        };
        // Only the waits compare the word, and they read it as Linux's
        // `futex_wait_setup` does, with user-mode permissions: EFAULT for an
        // unmapped, PROT_NONE or otherwise unreadable word
        // (https://github.com/rrnewton/hermit/issues/4030). A wake left to the
        // polling mode reads nothing, as Linux's `futex_wake` reads nothing.
        //
        // Linux checks a wait's other arguments first, without touching the
        // word: `sys_futex` (kernel/futex/syscalls.c) copies and validates the
        // timeout (EFAULT, EINVAL), then `__futex_wait` refuses a zero bitset
        // (EINVAL). A restarted wait keeps its validated deadline.
        let init_val = match call.futex_op() & libc::FUTEX_CMD_MASK {
            command @ (libc::FUTEX_WAIT | libc::FUTEX_WAIT_BITSET) => {
                if matches!(deadline, FutexDeadline::FromCall)
                    && let Some(timeout) = call.timeout()
                {
                    let timeout = read_user_timespec(guest, timeout.as_raw())?;
                    if !futex_timespec_is_valid(timeout) {
                        return Err(Error::Errno(Errno::EINVAL));
                    }
                }
                if command == libc::FUTEX_WAIT_BITSET && call.val3() == 0 {
                    return Err(Error::Errno(Errno::EINVAL));
                }
                read_futex_word(guest, AddrMut::as_raw(ptr))?
            }
            _ => 0,
        };
        trace!(
            "[detcore, dtid {}] futex op with memory address containing value {}",
            &dettid, init_val
        );
        if polling {
            self.handle_futex_polling(guest, call, init_val, deadline)
                .await
        } else {
            self.handle_futex_blocking(guest, call, init_val, deadline)
                .await
        }
    }

    /// Blocking (precise) Futex implementation.
    /// Here we use a two-phase request to the scheduler: before and after the futex wait/wake
    /// side effects. We EMULATE futex calls and NEVER run them inside the kernel.
    pub(crate) async fn handle_futex_blocking<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
        init_val: i32,
        deadline: FutexDeadline,
    ) -> Result<i64, Error> {
        let ptr = call.uaddr().unwrap();
        let futexid = guest.thread_state().futex_id(
            AddrMut::as_raw(ptr),
            call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0,
        );
        let futex_op = call.futex_op() & libc::FUTEX_CMD_MASK;
        let bitset = match futex_op {
            libc::FUTEX_WAKE_BITSET | libc::FUTEX_WAIT_BITSET => call.val3() as u32,
            _ => u32::MAX,
        };
        if bitset == 0 {
            return Err(Error::Errno(Errno::EINVAL));
        }
        let dettid = guest.thread_state().dettid;
        match futex_op {
            libc::FUTEX_WAIT | libc::FUTEX_WAIT_BITSET => {
                if init_val != call.val() {
                    info!(
                        "[detcore, dtid {}] Futex wait running immediately because it will fizzle ({} != {}).",
                        &dettid,
                        init_val,
                        call.val()
                    );
                    Err(Error::Errno(Errno::EAGAIN))
                } else {
                    let maybe_timeout_lt = self.futex_deadline(guest, call, deadline).await?;
                    // D50 reader 9 (A5 step 3c.1c): the capability, or the
                    // in-guest delivery gate, which decides by the design's
                    // deliverable set under the thread's published mask.
                    let gated = guest.config().in_guest_signal_delivery;
                    let signal_interruption = guest
                        .config()
                        .backend
                        .supports_blocked_wait_signal_interruption
                        || gated;
                    // Whether this wait was woken for a signal and is checking again.
                    let mut rewait = false;
                    // The signals the scheduler committed to this waiter at that wake
                    // (`SchedValue::Signaled`), which this turn's check counts although
                    // the wait holds them (https://github.com/rrnewton/hermit/issues/4005).
                    let mut committed_wake: KernelSigset = 0;
                    // Whether a wait request reached the scheduler. A wait that
                    // ends before its first one, on a pending signal or a failed
                    // read, sends no `WaitFinished`, as before.
                    let mut requested = false;
                    let res = loop {
                        // On a backend whose kernel reports the guest's signal state,
                        // a blocked, ignored, or default-ignored signal leaves the wait
                        // parked until its wakeup or its original deadline. As in
                        // Linux, one already pending when the value matches ends the
                        // wait at once with the futex's restart errno. A `SIGCHLD`
                        // ends it only when the scheduler committed it to this
                        // waiter at its wake, sent at a commit point (a child's
                        // child-exit timer, or a POSIX timer: `committed_wake`,
                        // https://github.com/rrnewton/hermit/issues/4005), or when it
                        // is a guest's thread-directed copy in this thread's private
                        // queue that the schedule recorded (`futex_wait_pending_signals`,
                        // https://github.com/rrnewton/hermit/issues/4132); any other
                        // stays pending until the call returns, because the kernel
                        // also posts one for a child event at a moment set by host
                        // timing (https://github.com/rrnewton/hermit/issues/3146). Nor does
                        // a signal that a host-timed source armed by a guest can
                        // post to this process, such as a parent-death signal
                        // (`host_timed_signals`, read here in this thread's turn).
                        //
                        // The same check decides a wait the scheduler woke for a
                        // signal. The scheduler commits such a wake without this
                        // thread running, and queues the thread to run next so that it
                        // is the thread that dequeues the signal. Checking again here,
                        // in the thread's own turn, keeps the restart errno for a
                        // signal the kernel will deliver to this thread as the call
                        // returns. If another thread took the signal first (a chaos
                        // schedule can run one ahead) or it became ignored, the wait
                        // parks again with its original absolute deadline, as
                        // `__futex_wait` retries a wait woken with no signal pending:
                        // an expired deadline ends it at the scheduler's next timed pop
                        // with ETIMEDOUT. Before parking again it reads the word, as
                        // `futex_wait_setup` does on that retry (see the re-check below).
                        // Returning the restart errno with nothing to deliver would
                        // instead have leaked it to the guest, or restarted the call
                        // with a fresh timeout.
                        //
                        // The scheduler is given only the mask, which only this thread
                        // can change and so cannot change while it is parked. A sibling
                        // can change the dispositions at any time, so the scheduler
                        // reads them when it commits a wake, not here
                        // (https://github.com/rrnewton/hermit/issues/3146).
                        let signal_watch = match self
                            .futex_wait_signal_watch(
                                guest,
                                call,
                                gated,
                                signal_interruption,
                                &mut committed_wake,
                            )
                            .await
                        {
                            Ok(watch) => watch,
                            Err(error) => break Err(error),
                        };
                        if rewait {
                            // No signal is pending for this thread, so Linux's
                            // `__futex_wait` retries `futex_wait_setup`, which reads the
                            // word again with user-mode permissions: EFAULT if it cannot,
                            // EAGAIN if it changed, and otherwise the wait parks again
                            // (https://github.com/rrnewton/hermit/issues/4033). While the
                            // wait was off the waiter list a `FUTEX_WAKE` could not reach
                            // it, and a waker that saw no waiter is consistent with
                            // exactly this retry window.
                            let observed = match read_futex_word(guest, AddrMut::as_raw(ptr)) {
                                Ok(observed) => observed,
                                Err(error) => break Err(error),
                            };
                            if observed != call.val() {
                                trace!(
                                    "[detcore, dtid {}] futex value changed while its wait was woken for a signal ({} != {}); EAGAIN",
                                    &dettid,
                                    observed,
                                    call.val()
                                );
                                break Err(Error::Errno(Errno::EAGAIN));
                            }
                            debug!(
                                "[detcore, dtid {}] futex wait woken for a signal that is not pending for it; waiting again until {:?}",
                                &dettid, maybe_timeout_lt
                            );
                        }
                        requested = true;
                        let ans = futex_action(
                            guest,
                            FutexAction::WaitRequest(maybe_timeout_lt, signal_watch),
                            &futexid,
                            init_val,
                            bitset,
                        )
                        .await;
                        if signal_interruption && let Some(SchedValue::Signaled(committed)) = ans {
                            committed_wake = committed;
                            // The scheduler ended the wait for a signal that
                            // interrupted it under the dispositions the kernel held
                            // when the wake was committed. The check at the top of the
                            // loop decides, in this thread's turn, whether it is still
                            // pending here.
                            rewait = true;
                            continue;
                        }
                        break if ans != Some(SchedValue::TimeOut) {
                            let expected = call.val();
                            // AUTONOMOUS-BOT-IMPLEMENTED
                            // TODO-HUMAN-REVIEW(#845): Review exited-thread futex diagnostics.
                            match guest.memory().read_value(ptr) {
                                Ok(observed) => {
                                    trace!(
                                        "[detcore, dtid {}] after (emulated) futex wait, memory value is {}, expected {}",
                                        &dettid, observed, expected,
                                    );
                                    if expected == observed {
                                        debug!(
                                            "WARNING: fishy that the futex value did not change before wakeup. Weird application-level protocol.\n"
                                        );
                                    }
                                }
                                Err(error) => trace!(
                                    "[detcore, dtid {}] skipped post-wait futex memory diagnostic: {}",
                                    &dettid, error,
                                ),
                            }
                            Ok(0)
                        } else {
                            trace!("[detcore, dtid {}] futex wait timed out", &dettid);
                            Err(Error::Errno(Errno::ETIMEDOUT))
                        };
                    };
                    if requested {
                        futex_action(guest, FutexAction::WaitFinished, &futexid, init_val, bitset)
                            .await;
                    }
                    keep_restart_block(guest, &res, RestartCall::Futex(call), maybe_timeout_lt)
                        .await;
                    res
                }
            }
            // `classify_futex_command` already answered every other command.
            _ => Err(Error::Errno(Errno::ENOSYS)),
        }
    }

    /// The check a precise futex wait makes before it parks, and again in its
    /// own turn after the scheduler woke it for a signal (see
    /// `Self::handle_futex_blocking`): `Err` with the call's restart errno
    /// when a signal pending for this thread ends the wait, otherwise what the
    /// scheduler watches while the thread is parked. `committed_wake` holds the
    /// signals the scheduler committed to this waiter at its last wake, which
    /// this check counts and clears.
    async fn futex_wait_signal_watch<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
        gated: bool,
        signal_interruption: bool,
        committed_wake: &mut KernelSigset,
    ) -> Result<Option<FutexSignalWatch>, Error> {
        let dettid = guest.thread_state().dettid;
        if gated {
            // Under the gate: a deliverable signal pending at
            // the park, or still pending after a wake, ends the
            // wait with the futex's restart errno, its end
            // recorded for the restart checkpoint (D40).
            let state = read_wait_signal_state(guest.pid(), guest.tid())?;
            let mask = super::helpers::gated_own_mask(guest, state.blocked);
            if let Some(end) = crate::wait_signal_end::wait_end(
                &state,
                mask,
                guest.config().in_guest_reserved_signals,
            ) {
                let errno = call.kernel_restart_errno();
                trace!(
                    "[detcore, dtid {}] futex wait ended under the in-guest delivery gate by {:?}: {:?}",
                    &dettid, end, errno
                );
                guest.thread_state_mut().wait_signal_end = Some(end);
                return Err(Error::Errno(errno));
            }
            // The futex wait files no `Resources` request, so
            // it publishes the guest's mask itself, before its
            // wait request, as every request does under the gate
            // (step 3c.1b, carried into 3c.1c): the scheduler's
            // readers then see this wait's mask, not an earlier
            // request's. None clears the entry, as at a request.
            let published =
                crate::tool_global::publish_request_guest_mask(guest, &Resources::new(dettid));
            crate::tool_global::set_saved_guest_sigmask(guest, published).await;
            Ok(Some(FutexSignalWatch {
                unblocked: !mask & !kernel_sigset_bit(reverie::PERF_EVENT_SIGNAL as i32),
                defers_default_stops: call.restart_keeps_deadline(),
                pid: guest.pid().as_raw(),
                tid: guest.tid().as_raw(),
            }))
        } else if signal_interruption {
            // A failed read is never the call's errno
            // (`read_wait_signal_state`).
            let state = read_wait_signal_state(guest.pid(), guest.tid())?;
            // A timed futex wait lets a default job-control stop
            // wait for its deadline (`KernelSignalState::interrupting_wait`).
            let defers_default_stops = call.restart_keeps_deadline();
            let host_timed = host_timed_signals(guest).await;
            let committed = std::mem::take(committed_wake);
            let held = futex_wait_held_after_wake(host_timed, committed);
            let pending = futex_wait_pending_signals(
                guest,
                &state,
                state.pending_interrupting(state.blocked, defers_default_stops),
                held,
                host_timed,
                committed,
            )
            .await;
            if pending != 0 {
                let errno = call.kernel_restart_errno();
                trace!(
                    "[detcore, dtid {}] futex wait interrupted by pending signals {:#x}: {:?}",
                    &dettid, pending, errno
                );
                return Err(Error::Errno(errno));
            }
            Ok(Some(FutexSignalWatch {
                unblocked: !state.blocked & !kernel_sigset_bit(reverie::PERF_EVENT_SIGNAL as i32),
                defers_default_stops,
                pid: guest.pid().as_raw(),
                tid: guest.tid().as_raw(),
            }))
        } else {
            Ok(None)
        }
    }

    /// What the scheduler holds for the PI futex `futexid`, whose word holds
    /// `word` (`Scheduler::pi_futex_state`), or `None` for a logically killed
    /// caller, which the scheduler answers with a plain value and which never
    /// returns to the guest.
    async fn pi_futex_state<G: Guest<Self>>(
        &self,
        guest: &mut G,
        futexid: &FutexID,
        word: u32,
    ) -> Option<PiFutexState> {
        match futex_action(
            guest,
            FutexAction::PiState(pi_futex::word_owner(word)),
            futexid,
            word as i32,
            u32::MAX,
        )
        .await
        {
            Some(SchedValue::PiFutex(state)) => Some(state),
            _ => None,
        }
    }

    /// FUTEX_LOCK_PI, FUTEX_LOCK_PI2 and FUTEX_TRYLOCK_PI, as Linux's
    /// `futex_lock_pi` (kernel/futex/pi.c:918-1125 at v6.16), in its order:
    /// - a LOCK_PI or LOCK_PI2 timeout is copied and checked first (`EFAULT`,
    ///   `EINVAL`), by `sys_futex` (kernel/futex/syscalls.c:168-175). It is an
    ///   absolute deadline, on CLOCK_REALTIME for LOCK_PI and on CLOCK_MONOTONIC
    ///   for LOCK_PI2 unless it sets FUTEX_CLOCK_REALTIME (`futex_init_timeout`,
    ///   syscalls.c:147-157). TRYLOCK_PI takes none (`futex_cmd_has_timeout`);
    /// - the word is keyed for writing (`get_futex_key`: `EINVAL` misaligned,
    ///   `EFAULT`) and read (`EFAULT`);
    /// - `pi_futex::lock_pi_step` decides, as `futex_lock_pi_atomic` does, from
    ///   the word and the scheduler's state for it; a word it changes is written
    ///   with the guest's permissions (`EFAULT`);
    /// - a blocked caller parks as a PI waiter behind the owner. It ends handed
    ///   the lock (0), at its deadline (`ETIMEDOUT`), or for a pending signal
    ///   with `ERESTARTNOINTR`, which the kernel always restarts (pi.c:1124);
    ///   the restarted call starts over and reads its absolute deadline again,
    ///   as Linux's does.
    ///
    /// A waiter handed the lock by its owner's death writes its own TID into the
    /// word (`pi_futex::owner_death_word`). A waiter handed the lock and then
    /// signalled before its turn keeps the lock, as Linux's
    /// `rt_mutex_cleanup_proxy_lock` keeps it (pi.c:1067-1068).
    ///
    /// The word holds a TID as the caller's PID namespace numbers it. Detcore's
    /// thread IDs are the container namespace's, so a caller in a nested PID
    /// namespace is refused by name.
    ///
    /// The read and write of the word are atomic with respect to the guest:
    /// Detcore runs one guest thread at a time and this one holds the turn, so
    /// none of the kernel's compare-and-exchange retries arises. A word in a
    /// file-backed shared mapping, which a process outside Hermit could change,
    /// is refused by name, as FUTEX_WAKE_OP's is.
    // TODO-HUMAN-REVIEW(#4616): Review the emulated priority-inheritance lock:
    // its word transitions, first-in-first-out waiter order and owner-death
    // hand-over.
    async fn handle_futex_lock_pi<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
        command: i32,
    ) -> Result<i64, Error> {
        let trylock = command == libc::FUTEX_TRYLOCK_PI;
        let name = pi_lock_command_name(command).expect("a PI lock command");
        if guest.thread_state().nested_pid_namespace {
            return self
                .refuse_futex_command(guest, name, NESTED_PID_NAMESPACE_REFUSAL)
                .await;
        }
        if !trylock && let Some(timeout) = call.timeout() {
            let timeout = read_user_timespec(guest, timeout.as_raw())?;
            if !futex_timespec_is_valid(timeout) {
                return Err(Error::Errno(Errno::EINVAL));
            }
        }
        let private = call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0;
        let uaddr = futex_uaddr(&call);
        let futexid = futex_key(guest, uaddr, private, KeyAccess::Write).await?;
        if futex_word_is_file_backed(guest, uaddr) {
            return self
                .refuse_futex_command(guest, name, FILE_BACKED_WORD_REFUSAL)
                .await;
        }
        let dettid = guest.thread_state().dettid;
        let caller = pi_futex::guest_tid(dettid);
        let gated = guest.config().in_guest_signal_delivery;
        let signal_interruption = guest
            .config()
            .backend
            .supports_blocked_wait_signal_interruption
            || gated;
        // The deadline, computed once, at the first park.
        let mut deadline: Option<Option<LogicalTime>> = None;
        let mut committed_wake: KernelSigset = 0;
        // The signal check made after a wake for a signal, before the word is
        // read again.
        let mut rewait_watch: Option<Option<FutexSignalWatch>> = None;
        let mut requested = false;
        let res = loop {
            let word = match read_futex_word(guest, uaddr) {
                Ok(word) => word as u32,
                Err(error) => break Err(error),
            };
            let Some(state) = self.pi_futex_state(guest, &futexid, word).await else {
                break Err(Error::Errno(Errno::ERESTARTNOINTR));
            };
            let step = pi_futex::lock_pi_step(word, caller, state, trylock);
            trace!(
                "[detcore, dtid {}] {:?} on the word at {:#x}, holding {:#x}, with {:?}: {:?}",
                dettid,
                pi_lock_command_name(command),
                uaddr,
                word,
                state,
                step
            );
            let (owner, write) = match step {
                LockPiStep::Fail { errno, write } => {
                    break write
                        .map_or(Ok(()), |value| write_futex_word(guest, uaddr, value))
                        .and(Err(Error::Errno(errno)));
                }
                LockPiStep::Acquire(value) => {
                    break write_futex_word(guest, uaddr, value).map(|()| 0);
                }
                LockPiStep::Block { owner, write } => (owner, write),
            };
            if let Some(value) = write
                && let Err(error) = write_futex_word(guest, uaddr, value)
            {
                break Err(error);
            }
            let signal_watch = match rewait_watch.take() {
                Some(watch) => watch,
                None => match self
                    .futex_wait_signal_watch(
                        guest,
                        call,
                        gated,
                        signal_interruption,
                        &mut committed_wake,
                    )
                    .await
                {
                    Ok(watch) => watch,
                    Err(error) => break Err(error),
                },
            };
            let timeout = match deadline {
                Some(timeout) => timeout,
                None => {
                    let timeout = if trylock {
                        None
                    } else {
                        match self
                            .futex_timeout_deadline(guest, call.futex_op(), call.timeout())
                            .await
                        {
                            Ok(timeout) => timeout,
                            Err(error) => break Err(error),
                        }
                    };
                    *deadline.insert(timeout)
                }
            };
            requested = true;
            let answer = futex_action(
                guest,
                FutexAction::PiLockWait(timeout, signal_watch, owner),
                &futexid,
                word as i32,
                u32::MAX,
            )
            .await;
            match futex_action(guest, FutexAction::PiTake, &futexid, 0, u32::MAX).await {
                Some(SchedValue::PiTaken(Some(PiHandOver::Unlock))) => break Ok(0),
                Some(SchedValue::PiTaken(Some(PiHandOver::OwnerDeath))) => {
                    break write_futex_word(guest, uaddr, pi_futex::owner_death_word(caller))
                        .map(|()| 0);
                }
                _ => {}
            }
            match answer {
                Some(SchedValue::TimeOut) => break Err(Error::Errno(Errno::ETIMEDOUT)),
                Some(SchedValue::Signaled(committed)) if signal_interruption => {
                    // Linux's waiter stays queued unless the signal is still
                    // pending in its own turn: check that first, then decide
                    // again from the word.
                    committed_wake = committed;
                    match self
                        .futex_wait_signal_watch(
                            guest,
                            call,
                            gated,
                            signal_interruption,
                            &mut committed_wake,
                        )
                        .await
                    {
                        Ok(watch) => rewait_watch = Some(watch),
                        Err(error) => break Err(error),
                    }
                }
                // A wake for a signal where the backend does not report the
                // kernel's signal state, or a logically killed caller, which
                // never returns to the guest: the kernel restarts the call.
                _ => break Err(Error::Errno(Errno::ERESTARTNOINTR)),
            }
        };
        if requested {
            futex_action(guest, FutexAction::WaitFinished, &futexid, 0, u32::MAX).await;
        }
        res
    }

    /// FUTEX_UNLOCK_PI, as Linux's `futex_unlock_pi` (kernel/futex/pi.c:1132-1293
    /// at v6.16), in its order: the word is read first (`EFAULT`), only the
    /// thread it names may unlock it (`EPERM`), then it is keyed for writing
    /// (`EINVAL` misaligned, `EFAULT`), and `pi_futex::unlock_pi_step` decides:
    /// 0 for a word with no waiter, a hand-over to the longest PI waiter, whose
    /// TID is written with `FUTEX_WAITERS` before it is woken (`wake_futex_pi`),
    /// or `EINVAL` where the word and the queued waiters disagree. The word is
    /// written with the guest's permissions (`EFAULT`), atomically with respect
    /// to the guest for the reason `Self::handle_futex_lock_pi` gives.
    // TODO-HUMAN-REVIEW(#4616): Review the emulated priority-inheritance unlock
    // and its hand-over to the longest waiter.
    async fn handle_futex_unlock_pi<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
    ) -> Result<i64, Error> {
        if guest.thread_state().nested_pid_namespace {
            return self
                .refuse_futex_command(guest, "FUTEX_UNLOCK_PI", NESTED_PID_NAMESPACE_REFUSAL)
                .await;
        }
        let uaddr = futex_uaddr(&call);
        let word = read_futex_word(guest, uaddr)? as u32;
        let dettid = guest.thread_state().dettid;
        if pi_futex::word_owner(word) != pi_futex::guest_tid(dettid) {
            return Err(Error::Errno(Errno::EPERM));
        }
        let private = call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0;
        let futexid = futex_key(guest, uaddr, private, KeyAccess::Write).await?;
        if futex_word_is_file_backed(guest, uaddr) {
            return self
                .refuse_futex_command(guest, "FUTEX_UNLOCK_PI", FILE_BACKED_WORD_REFUSAL)
                .await;
        }
        let Some(state) = self.pi_futex_state(guest, &futexid, word).await else {
            return Err(Error::Errno(Errno::ERESTARTNOINTR));
        };
        let step = pi_futex::unlock_pi_step(dettid, state);
        trace!(
            "[detcore, dtid {}] FUTEX_UNLOCK_PI on the word at {:#x}, holding {:#x}, with {:?}: {:?}",
            dettid, uaddr, word, state, step
        );
        match step {
            UnlockPiStep::Fail(errno) => Err(Error::Errno(errno)),
            UnlockPiStep::Release => write_futex_word(guest, uaddr, 0).map(|()| 0),
            UnlockPiStep::HandOff { write, .. } => {
                write_futex_word(guest, uaddr, write)?;
                // The state was read in this turn, so its next owner is still
                // queued; a logically killed caller is answered EINTR instead.
                let woken = match futex_action(guest, FutexAction::PiHandOff, &futexid, 0, u32::MAX)
                    .await
                {
                    Some(SchedValue::Value(1)) => 1,
                    Some(SchedValue::Value(e)) if e == nix::errno::Errno::EINTR as u64 => 0,
                    other => panic!("impossible answer to a PI futex hand-over: {:?}", other),
                };
                if self.cfg.yields_after_futex_wake(woken) {
                    guest.thread_state_mut().yield_after_futex_wake = true;
                }
                Ok(0)
            }
        }
    }

    /// FUTEX_WAKE and FUTEX_WAKE_BITSET, as Linux's `futex_wake`
    /// (kernel/futex/waitwake.c): `-EINVAL` for a zero bitset, then the word is
    /// keyed for reading (`futex_key`) and never read, and up to `val` modeled
    /// waiters whose bitset matches are woken (a count of 0 or below wakes one).
    async fn handle_futex_wake<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
        command: i32,
    ) -> Result<i64, Error> {
        let bitset = if command == libc::FUTEX_WAKE_BITSET {
            call.val3() as u32
        } else {
            u32::MAX
        };
        if bitset == 0 {
            return Err(Error::Errno(Errno::EINVAL));
        }
        let private = call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0;
        let futexid = futex_key(guest, futex_uaddr(&call), private, KeyAccess::Read).await?;
        let num = match futex_action(
            guest,
            FutexAction::WakeRequest(call.val()),
            &futexid,
            0,
            bitset,
        )
        .await
        .expect("futex wake must return value")
        {
            SchedValue::Value(num) => num,
            // `futex_wake` stops with EINVAL at a PI waiter, after waking those
            // before it (kernel/futex/waitwake.c:180-199).
            SchedValue::PiWaiterReached { woken } => {
                if self.cfg.yields_after_futex_wake(woken) {
                    guest.thread_state_mut().yield_after_futex_wake = true;
                }
                return Err(Error::Errno(Errno::EINVAL));
            }
            other => panic!("impossible answer to a futex wake: {:?}", other),
        };
        let _ = futex_action(guest, FutexAction::WakeFinished(0), &futexid, 0, bitset).await;
        if self.cfg.yields_after_futex_wake(num) {
            guest.thread_state_mut().yield_after_futex_wake = true;
        }
        Ok(num as i64)
    }

    /// FUTEX_REQUEUE and FUTEX_CMP_REQUEUE on plain futexes, as Linux's
    /// `futex_requeue` (kernel/futex/requeue.c) with `requeue_pi == 0`, in its
    /// order:
    /// - `-EINVAL` if `nr_wake` (`val`) or `nr_requeue` (`val2`, passed in the
    ///   timeout slot) is negative as an `int`, before any address is looked at;
    /// - both words keyed (`futex_key`): `-EINVAL` if misaligned, `-EFAULT` if
    ///   outside the user address range or, for a shared key, unmapped;
    /// - for FUTEX_CMP_REQUEUE only, the `uaddr` word read with the guest's own
    ///   permissions (`-EFAULT`), then `-EAGAIN` if it differs from `val3`.
    ///   Plain FUTEX_REQUEUE never reads either word;
    /// - wake the first `nr_wake` waiters, move up to `nr_requeue` more onto
    ///   `uaddr2` (`Scheduler::requeue_futex_waiters`), and return how many were
    ///   woken plus moved.
    // TODO-HUMAN-REVIEW(https://github.com/rrnewton/hermit/pull/4020): Review the
    // emulated futex requeue and its waiter ordering.
    async fn handle_futex_requeue<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
        command: i32,
    ) -> Result<i64, Error> {
        let nr_wake = call.val();
        let nr_requeue = futex_val2(&call) as i32;
        if nr_wake < 0 || nr_requeue < 0 {
            return Err(Error::Errno(Errno::EINVAL));
        }
        let private = call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0;
        let uaddr = futex_uaddr(&call);
        let futexid = futex_key(guest, uaddr, private, KeyAccess::Read).await?;
        let futexid2 = futex_key(guest, futex_uaddr2(&call), private, KeyAccess::Read).await?;
        let mut current = 0;
        if command == libc::FUTEX_CMP_REQUEUE {
            current = read_futex_word(guest, uaddr)?;
            if current != call.val3() {
                return Err(Error::Errno(Errno::EAGAIN));
            }
        }
        let woken_and_moved = match futex_action(
            guest,
            FutexAction::RequeueRequest(futexid2, nr_wake as u32, nr_requeue as u32),
            &futexid,
            current,
            u32::MAX,
        )
        .await
        {
            Some(SchedValue::Requeued { woken, moved }) => {
                if self.cfg.yields_after_futex_wake(woken) {
                    guest.thread_state_mut().yield_after_futex_wake = true;
                }
                woken + moved
            }
            // A logically killed or replaced caller is answered with a plain value, as
            // its wakes are; it never returns to the guest.
            Some(SchedValue::Value(num)) => num,
            // `futex_requeue` stops with EINVAL at a PI waiter, keeping what it
            // woke and moved before it (kernel/futex/requeue.c:585-603).
            Some(SchedValue::PiWaiterReached { woken }) => {
                if self.cfg.yields_after_futex_wake(woken) {
                    guest.thread_state_mut().yield_after_futex_wake = true;
                }
                return Err(Error::Errno(Errno::EINVAL));
            }
            other => panic!("impossible answer to a futex requeue: {:?}", other),
        };
        let _ = futex_action(
            guest,
            FutexAction::WakeFinished(0),
            &futexid,
            current,
            u32::MAX,
        )
        .await;
        Ok(woken_and_moved as i64)
    }

    /// FUTEX_WAKE_OP, as Linux's `futex_wake_op` (kernel/futex/waitwake.c), in
    /// its order: key both words (`futex_key`; the `uaddr` word is never read);
    /// apply the operation encoded in `val3` to the word at `uaddr2`
    /// (`futex_atomic_op_inuser`); wake up to `nr_wake` (`val`) waiters on
    /// `uaddr` and, if the encoded comparison of the old value holds, up to
    /// `nr_wake2` (`val2`, in the timeout slot) waiters on `uaddr2`. Returns the
    /// total woken.
    /// - An unknown operation is `-ENOSYS` before the word is touched; an
    ///   unknown comparison is `-ENOSYS` after it was written, and nobody is
    ///   woken. So a private NULL `uaddr2` (a valid key) with an unknown
    ///   operation is `-ENOSYS`.
    /// - The word is read and written as exactly four bytes with the guest's own
    ///   permissions, so an unreadable or unwritable word is `-EFAULT` and a word
    ///   at the end of a page next to a hole is fine.
    ///
    /// Both wakes count a waiter before comparing, so a count of 0 or below wakes
    /// one, and neither looks at the waiters' bitsets, as `futex_wake_op` does not.
    /// The read-modify-write is atomic with respect to the guest because Detcore
    /// runs one guest thread at a time and this one holds the turn, and only
    /// guest threads can reach a private or anonymous shared word. A word in a
    /// file-backed shared mapping can also be written by a process outside
    /// Hermit, which Linux's locked instruction would not lose, so that case is
    /// refused by name before any side effect.
    // TODO-HUMAN-REVIEW(https://github.com/rrnewton/hermit/pull/4020): Review the
    // emulated FUTEX_WAKE_OP and its read-modify-write of the guest word.
    async fn handle_futex_wake_op<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
    ) -> Result<i64, Error> {
        let nr_wake = call.val();
        let nr_wake2 = futex_val2(&call) as i32;
        let private = call.futex_op() & libc::FUTEX_PRIVATE_FLAG != 0;
        let uaddr2 = futex_uaddr2(&call);
        let futexid = futex_key(guest, futex_uaddr(&call), private, KeyAccess::Read).await?;
        let futexid2 = futex_key(guest, uaddr2, private, KeyAccess::Write).await?;
        let op = FutexWakeOp::decode(call.val3() as u32);
        if !op.has_known_operation() {
            return Err(Error::Errno(Errno::ENOSYS));
        }
        if futex_word_is_file_backed(guest, uaddr2) {
            return self
                .refuse_futex_command(guest, "FUTEX_WAKE_OP", FILE_BACKED_WORD_REFUSAL)
                .await;
        }
        let old = read_futex_word(guest, uaddr2)?;
        let new = op.apply(old).expect("operation was checked to be known");
        write_futex_word(guest, uaddr2, new as u32)?;
        let Some(wake2) = op.compare(old) else {
            return Err(Error::Errno(Errno::ENOSYS));
        };
        let mut woken = 0;
        for (futex, count, wake) in [(futexid, nr_wake, true), (futexid2, nr_wake2, wake2)] {
            if !wake {
                continue;
            }
            woken += match futex_action(guest, FutexAction::WakeRequest(count), &futex, 0, u32::MAX)
                .await
            {
                Some(SchedValue::Value(num)) => num,
                // `futex_wake_op` stops with EINVAL at a PI waiter, after the
                // operation (kernel/futex/waitwake.c:301-303, 315-317).
                Some(SchedValue::PiWaiterReached { woken: num }) => {
                    if self.cfg.yields_after_futex_wake(woken + num) {
                        guest.thread_state_mut().yield_after_futex_wake = true;
                    }
                    return Err(Error::Errno(Errno::EINVAL));
                }
                other => panic!("impossible answer to a futex wake: {:?}", other),
            };
            let _ = futex_action(guest, FutexAction::WakeFinished(0), &futex, 0, u32::MAX).await;
        }
        if self.cfg.yields_after_futex_wake(woken) {
            guest.thread_state_mut().yield_after_futex_wake = true;
        }
        Ok(woken as i64)
    }

    /// Refuse a futex command Detcore cannot serve deterministically, naming it,
    /// through the unsupported-syscall policy (`refuse_unserviceable_operation`).
    /// A run that is not fail-closed gets `-ENOSYS`, which is what Linux returns
    /// for every priority-inheritance command when built without CONFIG_FUTEX_PI
    /// (kernel/futex/pi.c, kernel/futex/requeue.c).
    async fn refuse_futex_command<G: Guest<Self>>(
        &self,
        guest: &mut G,
        name: &'static str,
        reason: &'static str,
    ) -> Result<i64, Error> {
        tracing::error!(
            "[detcore, dtid {}] futex command {} is not supported: {}",
            guest.thread_state().dettid,
            name,
            reason,
        );
        self.refuse_unserviceable_operation(guest, reverie::syscalls::Sysno::futex, Errno::ENOSYS)
            .await
    }

    /// Futex system call, alternative implemenattion where we treat futexes as InternalIOPolling
    /// operations.
    pub(crate) async fn handle_futex_polling<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Futex,
        init_val: i32,
        deadline: FutexDeadline,
    ) -> Result<i64, Error> {
        fn make_futex_wake_request(dettid: DetTid) -> Resources {
            let mut rsrc = Resources::new(dettid);
            rsrc.fyi("futex_wake");
            rsrc
        }

        fn make_futex_wait_request(dettid: DetTid) -> Resources {
            let mut rsrc = Resources::new(dettid);
            rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
            rsrc.fyi("futex_wait");
            rsrc
        }

        let dettid = guest.thread_state().dettid;
        let futex_op = call.futex_op() & libc::FUTEX_CMD_MASK;
        match futex_op {
            libc::FUTEX_WAKE | libc::FUTEX_WAKE_BITSET => {
                let rsrc = make_futex_wake_request(dettid);
                resource_request(guest, rsrc.clone()).await; // Linearize this operation as a separate COMMIT.
                let res = guest.inject(call).await;
                // FIXME: With the non-blocking version of futex_wait, `res` will always be 0.  It
                // is quite difficult to tell how many polling waiters we unblocked with a given
                // wake, without going back to modeling futexes like `handle_futex_blocking` does.
                Ok(res?)
            }
            libc::FUTEX_WAIT | libc::FUTEX_WAIT_BITSET => {
                if init_val != call.val() {
                    info!(
                        "[detcore, dtid {}] Futex wait running immediately because it will fizzle ({} != {}).",
                        dettid,
                        init_val,
                        call.val()
                    );
                    let res = guest.inject(call).await;
                    Ok(res?)
                } else {
                    let rsrc = make_futex_wait_request(dettid);
                    let deadline = self.futex_deadline(guest, call, deadline).await?;
                    let res =
                        retry_nonblocking_syscall_with_timeout(guest, call, rsrc, deadline).await;
                    keep_restart_block(guest, &res, RestartCall::Futex(call), deadline).await;
                    let res = res?;
                    trace!(
                        "[detcore, dtid {}] after futex wait, memory value is {}",
                        &dettid,
                        guest.memory().read_value(call.uaddr().unwrap()).unwrap()
                    );
                    Ok(res)
                }
            }
            // `classify_futex_command` already answered every other command.
            _ => Err(Error::Errno(Errno::ENOSYS)),
        }
    }

    /// The image `call` runs if it succeeds
    /// ([`crate::exec_record::ExecRecord::resolve`]), looked up as the kernel
    /// will look it up: through the calling thread's root and working
    /// directory, or the directory descriptor, or with `AT_EMPTY_PATH` the
    /// descriptor itself. `None` where Detcore cannot see the thread's
    /// filesystem ([`Self::guest_task_directory`]) or the kernel would
    /// refuse the exec; the new image's `/proc/<pid>/exe` link is then the
    /// kernel's.
    fn exec_image<G: Guest<Self>>(
        &self,
        guest: &G,
        call: &syscalls::Execveat,
    ) -> Option<crate::exec_record::ExecRecord> {
        let path: std::path::PathBuf = call.path()?.read(&guest.memory()).ok()?;
        self.exec_image_at(guest, call.dirfd(), &path)
    }

    /// The image this one's exec ran, from the pathname the exec was given
    /// (`AT_EXECFN`), resolved as [`Self::exec_image`] resolves an `execve`'s
    /// from the working directory, which an exec keeps. For an exec Detcore
    /// did not prepare: a backend's copied vfork child runs its `execve`
    /// without Detcore. `None` where the auxiliary vector has no such entry
    /// or its string cannot be read.
    pub(crate) fn exec_image_from_execfn<G: Guest<Self>>(
        &self,
        guest: &G,
    ) -> Option<crate::exec_record::ExecRecord> {
        use reverie::syscalls::FromToRaw;
        let address = guest.auxv().at_execfn()?.as_raw();
        let path: std::path::PathBuf = Option::<syscalls::PathPtr>::from_raw(address)?
            .read(&guest.memory())
            .ok()?;
        self.exec_image_at(guest, libc::AT_FDCWD, &path)
    }

    /// The name this image's exec gave it as Linux names it from the
    /// filename the exec was given (`kbasename(bprm->filename)`,
    /// `procfs::task_stat::TaskComm::of_exec_filename`), read from the
    /// image's `AT_EXECFN`, which points at a copy of that filename on its
    /// initial stack (`create_elf_tables`). `None` where the auxiliary vector
    /// has no such entry or its string cannot be read.
    pub(crate) fn execfn_comm<G: Guest<Self>>(
        &self,
        guest: &G,
    ) -> Option<crate::procfs::task_stat::TaskComm> {
        use std::os::unix::ffi::OsStrExt;

        use reverie::syscalls::FromToRaw;
        let address = guest.auxv().at_execfn()?.as_raw();
        let path: std::path::PathBuf = Option::<syscalls::PathPtr>::from_raw(address)?
            .read(&guest.memory())
            .ok()?;
        Some(crate::procfs::task_stat::TaskComm::of_exec_filename(
            path.as_os_str().as_bytes(),
        ))
    }

    /// `Self::exec_image` for a `path` the caller already read from the
    /// guest: public for a backend that runs the native `execve` outside
    /// Detcore's handler, prepares the exec itself (`crate::prepare_exec`)
    /// and reads guest memory its own way.
    pub fn exec_image_at<G: Guest<Self>>(
        &self,
        guest: &G,
        dirfd: i32,
        path: &std::path::Path,
    ) -> Option<crate::exec_record::ExecRecord> {
        let task = self.guest_task_directory(guest)?;
        let root = std::fs::read_link(task.join("root")).ok()?;
        let inside = |link: std::path::PathBuf| {
            Some(std::path::Path::new("/").join(link.strip_prefix(&root).ok()?))
        };
        let cwd = inside(std::fs::read_link(task.join("cwd")).ok()?)?;
        let spelled = if path.is_absolute() || dirfd == libc::AT_FDCWD {
            cwd.join(path)
        } else {
            let descriptor = task.join("fd").join(dirfd.to_string());
            let directory = inside(std::fs::read_link(descriptor).ok()?)?;
            // An empty path names the descriptor itself; without
            // `AT_EMPTY_PATH` the exec fails, and the record with it.
            if path.as_os_str().is_empty() {
                directory
            } else {
                directory.join(path)
            }
        };
        // An exec of the caller's own `exe` link runs the image it executes,
        // which the link names, also where the kernel's link names the
        // guest's launcher (SaBRe's loader).
        match self.resolve_exe_subject(guest, &spelled, true) {
            Some(crate::syscalls::namespace::ExeLinkSubject::Own) => {
                return guest.thread_state().exe.as_deref().cloned();
            }
            // Another process's image, which only the coordinator records.
            Some(crate::syscalls::namespace::ExeLinkSubject::Other(_)) => return None,
            None => {}
        }
        crate::exec_record::ExecRecord::resolve(&root, &cwd, &spelled)
    }

    /// [`Self::exec_image`] where the tool cannot read the guest's procfs
    /// directory but sees the guest's files in its own filesystem view
    /// (`Detcore::exec_record_root` is `/`: KVM, whose executor opens every
    /// absolute guest path in the tool's own view), resolved as that
    /// executor resolves the exec (reverie-linuxemu's
    /// `resolve_guest_exec_image`): an absolute path as it is, a relative one
    /// with a slash from the working directory the calling thread's own
    /// `getcwd` gives, and an exec of the caller's own `exe` link spelled
    /// under `/proc` the image it executes. Only an ELF image is recorded:
    /// `None` for a script (the executor reads its interpreter its own way),
    /// for a name without a slash (which the executor searches on `PATH`,
    /// where Linux does not), for a path relative to a directory descriptor
    /// or empty (`AT_EMPTY_PATH`), for any other path under `/proc` (the
    /// tool's `/proc` is not the guest's), in a nested PID namespace, and for
    /// the tool's own image, which a path through the tool's `/proc` could
    /// have led to. Without a record the new image's `exe` link is the
    /// executor's, as before (`Detcore::readlink_own_task_link`); with one,
    /// Detcore answers only while it names the image exactly, and the
    /// executor holds the image open, so its inode cannot be reused meanwhile.
    async fn exec_image_without_procfs<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: &syscalls::Execveat,
    ) -> Option<crate::exec_record::ExecRecord> {
        use std::os::unix::ffi::OsStrExt;
        use std::os::unix::fs::MetadataExt;
        if crate::procfs_inode::tool_can_name_guest_descriptors(&self.cfg.backend)
            || guest.thread_state().nested_pid_namespace
        {
            return None;
        }
        let root = self.exec_record_root(guest)?;
        let path: std::path::PathBuf = call.path()?.read(&guest.memory()).ok()?;
        if path.as_os_str().is_empty()
            || (!path.is_absolute() && call.dirfd() != libc::AT_FDCWD)
            || (!path.is_absolute() && path.components().count() < 2)
        {
            return None;
        }
        let cwd = if path.is_absolute() {
            None
        } else {
            let directory = self.injected_working_directory(guest, None, 0).await.ok()?;
            Some(std::path::PathBuf::from(
                <std::ffi::OsString as std::os::unix::ffi::OsStringExt>::from_vec(directory),
            ))
            .filter(|directory| directory.is_absolute())
        };
        let spelled = match &cwd {
            Some(cwd) => cwd.join(&path),
            None => path.clone(),
        };
        let own_pid = self.own_detpid(guest).as_raw();
        if spelled.starts_with("/proc") {
            return match crate::syscalls::namespace::exe_link_subject(
                spelled.as_os_str().as_bytes(),
                own_pid,
            ) {
                Some(crate::syscalls::namespace::ExeLinkSubject::Own) => {
                    guest.thread_state().exe.as_deref().cloned()
                }
                _ => None,
            };
        }
        let record = crate::exec_record::ExecRecord::resolve_from(&root, cwd.as_deref(), &path)?;
        // The file the path names itself, which the record is only where it
        // is no script (a script's record is its interpreter's).
        let named = std::fs::metadata(root.join(spelled.strip_prefix("/").ok()?))
            .ok()
            .map(|metadata| (metadata.dev(), metadata.ino()));
        let tool_image = std::fs::metadata("/proc/self/exe")
            .ok()
            .map(|metadata| (metadata.dev(), metadata.ino()));
        (Some(record.identity()) == named && Some(record.identity()) != tool_image)
            .then_some(record)
    }

    /// Execveat system call.  Doesn't return if successful.
    pub async fn handle_execveat<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Execveat,
    ) -> Result<i64, Error> {
        self.promote_before_native_lifecycle(guest);
        let (old_metadata, old_memory_metadata, table_is_shared, dettid, detpid, old_mm_id) = {
            let thread_state = guest.thread_state();
            (
                Arc::clone(&thread_state.file_metadata),
                Arc::clone(&thread_state.memory_metadata),
                Arc::strong_count(&thread_state.file_metadata) > 1,
                thread_state.dettid,
                thread_state.detpid.expect("detpid unset"),
                thread_state.mm_id,
            )
        };
        let (mut new_metadata, closed_open_files, exec_fd_blocking) = {
            let metadata = old_metadata.lock().unwrap();
            // The exec'ing thread leads its process from here, alone.
            let mut new_metadata = metadata.for_exec(dettid);
            new_metadata.hold_alone(detpid);
            (
                new_metadata.clone(),
                metadata.open_files_closed_on_exec(table_is_shared),
                new_metadata.exec_blocking_overrides(),
            )
        };
        // The close-on-exec descriptors this exec drops from the old table go
        // at the new image's first callback, if the exec succeeds
        // (`Detcore::release_exec_dropped_descriptors`).
        self.keep_table_for_exec(guest, &old_metadata, &mut new_metadata, detpid);
        let preserve_exec_fd_status = guest.config().backend.rediscovers_descriptors_after_exec;
        let exe = match self.exec_image(guest, &call) {
            Some(exe) => Some(exe),
            None => self.exec_image_without_procfs(guest, &call).await,
        };

        prepare_exec(
            guest,
            old_mm_id,
            if preserve_exec_fd_status {
                exec_fd_blocking
            } else {
                Default::default()
            },
            // This handler stages the exec's owner-death wakes itself, below.
            Vec::new(),
            exe,
        )
        .await;

        let mut released_ports = Vec::new();
        for open_file_id in closed_open_files {
            if let Some(port) = self.release_port_for_open_file(guest, open_file_id).await {
                released_ports.push((open_file_id, port));
            }
        }

        // A successful execve walks every robust list in the thread group
        // before it replaces the address space (see
        // `ThreadState::stage_robust_list_wakes_for_exec`), then clears
        // `task->robust_list`; the new image re-registers its own. Read the
        // lists while the old image is still mapped.
        // Linux marks the owner words itself at a successful exec, and a failed
        // exec must leave them alone, so Detcore only reads them here. Only
        // where Linux's exec runs under this handler ([`OwnerDeathPath::Kernel`]):
        // on DBT Detcore never sees the execve, and a word the native client
        // does not rewrite to a TID Linux knows is never marked
        // (https://github.com/rrnewton/hermit/issues/4268).
        let exec_robust_wakes = match self.robust_owner_death_path() {
            Some(OwnerDeathPath::Kernel) => Some(
                self.read_thread_group_robust_list_wakes(guest, OwnerDeath::Exec)
                    .await,
            ),
            Some(OwnerDeathPath::Barrier) | None => None,
        };
        let old_robust_list_head;
        // The exec'ing thread leads its process after a successful exec, so
        // the table exec gives it is the process's (`process_files`), also
        // for a thread that did not lead it before.
        let old_process_files = guest.thread_state().process_files;

        {
            let thread_state = guest.thread_state_mut();
            thread_state.file_metadata = Arc::new(Mutex::new(new_metadata));
            thread_state.adopt_process_files();
            thread_state.memory_metadata = Arc::new(Mutex::new(MemoryMetadata::new()));
            thread_state.mm_id = old_mm_id.for_exec(detpid);
            old_robust_list_head = thread_state.take_robust_list_for_exec();
            if let Some(wakes) = exec_robust_wakes {
                thread_state.stage_robust_list_wakes_for_exec(wakes);
            }
        }

        // execve(2) doesn't return upon success.
        let errno = self.record_or_replay(guest, call).await.unwrap_err();
        // Ask before anything else is injected: the next injection replaces
        // the backend's record.
        let refusal = guest.take_unsupported_refusal();

        {
            let thread_state = guest.thread_state_mut();
            thread_state.file_metadata = old_metadata;
            thread_state.process_files = old_process_files;
            thread_state.memory_metadata = old_memory_metadata;
            thread_state.mm_id = old_mm_id;
            thread_state.restore_robust_list_after_failed_exec(old_robust_list_head);
            // The old image runs on, and so do its robust-mutex owners.
            thread_state.take_robust_list_wakes_for_exec();
        }

        cancel_exec(guest).await;
        for (open_file_id, port) in released_ports {
            self.restore_port_for_open_file(guest, open_file_id, port)
                .await;
        }

        // A backend that cannot perform this exec says so with a typed
        // refusal: for example one that cannot promote a worker thread to
        // group leader, which refuses after validating the replacement image,
        // and also when a host syscall its exec preflight makes (such as the
        // KVM backend's faccessat2 permission check) fails with ENOSYS.
        // Diagnose it only after normal failed-exec rollback. Any other
        // failure, including an ENOSYS the backend did not report as a
        // refusal, is the guest's ordinary exec error.
        if let Some(refusal) = refusal {
            tracing::error!(
                "[detcore, dtid {dettid}] {}; the replacement image did not run",
                refusal.diagnostic
            );
            if !self.cfg.panic_on_unsupported_syscalls {
                crate::tool_global::report_unsupported_syscall(guest, call.number()).await;
            }
            return self
                .refuse_unserviceable_operation_because(
                    guest,
                    call.number(),
                    errno,
                    refusal.diagnostic,
                )
                .await;
        }

        Err(errno.into())
    }

    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(#258): Confirm one-turn exclusion semantics across scheduler modes.
    /// End the current logical timeslice for a sequentialized sched_yield.
    pub async fn handle_sched_yield<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::SchedYield,
    ) -> Result<i64, Error> {
        if self.cfg.sequentialize_threads {
            match sched_yield_route(&self.cfg) {
                SchedYieldRoute::ChaosReprioritize => {
                    let change_time = guest.thread_state().thread_logical_time.as_nanos();
                    let request = Self::random_priority_changepoint_request(guest, change_time);
                    resource_request(guest, request).await;
                }
                SchedYieldRoute::ReplayStrongYield => {
                    if self.cfg.max_timeslice.is_some() {
                        guest
                            .thread_state_mut()
                            .reset_timeslice_for_explicit_yield();
                    }
                    let request = Self::sched_yield_request(guest);
                    resource_request(guest, request).await;
                }
                SchedYieldRoute::ChaosYieldEpoch => {
                    let request = Self::sched_yield_request(guest);
                    resource_request(guest, request).await;
                }
                SchedYieldRoute::WeakYield
                    if !self.cfg.chaos && guest.thread_state().slice_boundary.is_some() =>
                {
                    // Typed replay must observe this actual syscall's boundary,
                    // even if its expected marker is missing. The existing
                    // replay close still posts the weak-yield resource.
                    self.end_timeslice_for_sched_yield(guest).await;
                }
                SchedYieldRoute::WeakYield => {
                    let request = Self::yield_request(guest);
                    resource_request(guest, request).await;
                }
                SchedYieldRoute::EndTimeslice => self.end_timeslice_for_sched_yield(guest).await,
            }
            trace!("sched_yield yielded to the scheduler; NOT performing actual syscall");
            Ok(0)
        } else {
            Ok(self.record_or_replay(guest, call).await?)
        }
    }

    /// `child`'s pid as the calling thread names it: its DetTid at depth 0,
    /// its pid in the caller's namespace below that
    /// (https://github.com/rrnewton/hermit/issues/4090). Detcore picks the
    /// child of a wait itself and injects the exact wait, which the kernel
    /// reads in the caller's namespace.
    async fn guest_visible_pid<G: Guest<Self>>(
        &self,
        guest: &mut G,
        sysno: reverie::syscalls::Sysno,
        child: DetPid,
    ) -> Result<i32, Error> {
        if !guest.thread_state().nested_pid_namespace {
            return Ok(child.as_raw());
        }
        let refusal = match crate::tool_global::local_pid(guest, child).await {
            Ok(Some(local)) => return Ok(local),
            Ok(None) => format!("child {child} is not visible in the caller's namespace"),
            Err(reason) => reason,
        };
        Err(self.refuse_nested_pid(guest, sysno, &refusal).await)
    }

    /// The task a pid the kernel answered the calling thread with names: the
    /// pid itself at depth 0, translated from the caller's namespace below
    /// that, before it enters Detcore's bookkeeping
    /// (https://github.com/rrnewton/hermit/issues/4090).
    async fn task_of_guest_pid<G: Guest<Self>>(
        &self,
        guest: &mut G,
        sysno: reverie::syscalls::Sysno,
        pid: i32,
    ) -> Result<DetPid, Error> {
        if !guest.thread_state().nested_pid_namespace || pid <= 0 {
            return Ok(DetPid::from_raw(pid));
        }
        let refusal = match crate::tool_global::guest_pid(guest, pid).await {
            GuestPidAnswer::Task { task, .. } => return Ok(task),
            GuestPidAnswer::NoSuchPid => {
                format!("the kernel answered pid {pid}, which no recorded task has")
            }
            GuestPidAnswer::Untranslatable(reason) => reason,
        };
        Err(self.refuse_nested_pid(guest, sysno, &refusal).await)
    }

    /// Track the pidfd a `CLONE_PIDFD` clone wrote at `address` as
    /// `pidfd_open`'s is tracked: a close-on-exec pidfd naming the new
    /// process, `child`, so that `pidfd_send_signal`, `waitid(P_PIDFD)` and
    /// the descriptor calls know it. Before, Detcore did not know the
    /// descriptor, and `pidfd_send_signal` on it failed with EBADF
    /// (https://github.com/rrnewton/hermit/issues/4430). The kernel installs it
    /// in the caller's descriptor table after copying that table for the
    /// child, so the child does not have it; the child's Detcore table was
    /// copied while the clone ran, so the same holds there.
    ///
    /// Only a child that shares neither the caller's memory nor its
    /// descriptor table, and is no vfork child, gets here
    /// (`clone_pidfd_address`), and only with sequentialized threads: no other
    /// task can then run between the kernel's clone and this, in the caller's
    /// own turn, so neither the clone's arguments nor the word nor the
    /// descriptor can change in between. The clone has
    /// succeeded whatever happens here, so nothing here fails it: a pidfd
    /// that cannot be tracked stays open and unknown to Detcore (EBADF through
    /// it, as before), and the reason is logged.
    async fn register_clone_pidfd<G: Guest<Self>>(
        &self,
        guest: &mut G,
        address: usize,
        child: DetTid,
    ) {
        let dettid = guest.thread_state().dettid;
        let skip = |reason: String| {
            tracing::error!(
                "[detcore, dtid {}] the pidfd of CLONE_PIDFD child {} is not tracked: {}; pidfd \
                 calls through it answer EBADF (https://github.com/rrnewton/hermit/issues/4430)",
                dettid,
                child,
                reason,
            );
        };
        let fd: libc::c_int = match Addr::<libc::c_int>::from_raw(address)
            .map(|address| guest.memory().read_value(address))
        {
            Some(Ok(fd)) => fd,
            // The kernel wrote it, or the clone would have failed with EFAULT;
            // a task sharing the memory may have unmapped it since.
            _ => return skip(format!("its word at {address:#x} cannot be read back")),
        };
        // The kernel has just allocated it, so a number Detcore already
        // tracks means another thread of the caller rewrote the word.
        if guest.thread_state().with_detfd(fd, |_| ()).is_ok() {
            return skip(format!(
                "its word names descriptor {fd}, which Detcore already tracks"
            ));
        }
        if let Err(errno) = self
            .track_held_fd(
                guest,
                fd,
                nix::fcntl::OFlag::O_CLOEXEC,
                crate::fd::FdType::Pidfd,
            )
            .await
        {
            return skip(format!("tracking descriptor {fd} failed with {errno}"));
        }
        if let Err(error) = guest.thread_state().with_detfd(fd, |detfd| {
            detfd.set_pidfd_target(DetPid::from_raw(child.as_raw()))
        }) {
            skip(format!("descriptor {fd} has no Detcore entry: {error}"));
        }
    }

    /// Refuse, by name and through the unsupported-operation policy, a
    /// `clone3` whose `set_tid` asks for an id that a task of this run had
    /// (`thread_id_refused`): a reaped child's pid or an exited thread's tid,
    /// which Linux would give out again, or a live task's id, whose release
    /// can race the call (https://github.com/rrnewton/hermit/issues/4370).
    /// Detcore keeps per-task state by that id (the task's clock, its
    /// recorded schedule and preemptions, its priority), and a new task given
    /// it took over the old one's: the run crashed with "thread time should
    /// never go down", or recorded two tasks as one. `None` lets the call go
    /// ahead, and the kernel's own answer stands, whenever the call cannot
    /// reuse such an id or the kernel would fail it first: no `set_tid`; a
    /// `clone_args` size, exit signal or `set_tid` array the kernel rejects
    /// (E2BIG, EINVAL, EFAULT); a caller without the capability to choose a
    /// pid (EPERM); an id never used; or the pid of a zombie child of the
    /// caller's process (EEXIST).
    ///
    /// The entry that names Detcore's id is `set_tid[0]`, or `set_tid[1]`
    /// with `CLONE_NEWPID`, whose `set_tid[0]` is the pid inside the new
    /// namespace; any later entries name pids in the namespaces holding
    /// Hermit's container. Where those would make Linux fail the call, with
    /// EINVAL for more levels than exist or EPERM for a level the caller has
    /// no capability over, the refusal is given instead: the conservative
    /// side, since the id is not handed out either way. So is a nonzero tail
    /// past the fields this code knows, which a kernel that does not know
    /// them answers with E2BIG. From a nested PID namespace, whose pids
    /// Detcore does not translate for this, any `set_tid` the checks above
    /// let through is refused (issue 4155).
    async fn clone3_set_tid_refusal<G: Guest<Self>>(
        &self,
        guest: &mut G,
        clone: &syscalls::Clone3,
    ) -> Option<Result<i64, Error>> {
        // Refuse only a call the kernel would accept as far as `set_tid` goes:
        // any other shape goes to the kernel, whose own error stands. The
        // exceptions are deliberate, on the conservative side: a struct or
        // array Detcore cannot read although the kernel may is refused before
        // the kernel's later checks are known (EFAULT under
        // --allow-unsupported-syscalls), and so is CLONE_NEWTIME on a kernel
        // before 6.3, which refuses it with EINVAL. `struct clone_args`
        // carries `set_tid` at offset 64 and `set_tid_size` at offset 72.
        // The kernel zero-extends a shorter struct, so one of 73 bytes or
        // more can name a set_tid; a shorter one names none or is EINVAL.
        const SET_TID_SIZE_OFFSET: usize = 72;
        // The kernel's limit on PID namespace nesting (MAX_PID_NS_LEVEL).
        const MAX_SET_TID: u64 = 32;
        let size = clone.size();
        let page = usize::try_from(unsafe { libc::sysconf(libc::_SC_PAGESIZE) }).ok()?;
        if size <= SET_TID_SIZE_OFFSET || size > page {
            return None;
        }
        // The kernel copies all `size` bytes first: a fault there is its
        // EFAULT. A nonzero tail beyond the fields this code knows is not
        // read as a reason to let the call through, since a newer kernel may
        // accept it.
        // Read as copy_from_user reads it, with the guest's own access
        // (`chosen_ids::read_clone_args`). A struct every kernel refuses
        // (proved to fault included) goes to the kernel. One Detcore cannot
        // read although the kernel may (a page mapped writable, not readable,
        // or a mapped page 0) cannot be checked, so it is refused below.
        let witness = super::chosen_ids::FaultWitness::for_backend(
            &guest.config().backend,
            guest.tid().as_raw(),
        );
        let memory = guest.memory();
        let mut raw = match super::chosen_ids::read_clone_args(&memory, witness, clone) {
            super::chosen_ids::Clone3Read::Bytes(bytes) => bytes,
            super::chosen_ids::Clone3Read::Refused => return None,
            super::chosen_ids::Clone3Read::Unreadable { .. } => {
                return Some(
                    self.refuse_unchecked_set_tid(
                        guest,
                        "clone3's struct clone_args cannot be read with the guest's own access",
                    )
                    .await,
                );
            }
        };
        // Zero-extended, as the kernel extends a shorter struct.
        if raw.len() < super::chosen_ids::CLONE_ARGS_SIZE_VER2 {
            raw.resize(super::chosen_ids::CLONE_ARGS_SIZE_VER2, 0);
        }
        let field = |offset: usize| u64::from_ne_bytes(raw[offset..offset + 8].try_into().unwrap());
        let flags = field(0);
        let exit_signal = field(32);
        let set_tid = field(64);
        let set_tid_size = field(72);
        if !clone3_signal_fields_valid(flags, exit_signal) {
            return None;
        }
        if set_tid_size == 0 || set_tid_size > MAX_SET_TID {
            return None;
        }
        // The kernel copies the whole array next (EFAULT) and takes no entry
        // below 1 (EINVAL).
        let mut tids = vec![0 as libc::pid_t; set_tid_size as usize];
        if !super::chosen_ids::within_user_memory(
            set_tid as usize,
            tids.len() * std::mem::size_of::<libc::pid_t>(),
        ) {
            return None;
        }
        if set_tid == 0 {
            // Linux: EINVAL, before reading anything.
            return None;
        }
        // A fault the kernel must take too is its EFAULT. Otherwise an array
        // Detcore cannot read (a page mapped writable, not readable) may
        // still be read by the kernel: it is refused below, once the checks
        // that need no entry have passed, since its ids cannot be checked.
        let read =
            super::chosen_ids::read_pid_array(&memory, set_tid as usize, &mut tids).is_some();
        if !read
            && super::chosen_ids::range_faults(
                witness,
                set_tid as usize,
                tids.len() * std::mem::size_of::<libc::pid_t>(),
            )
        {
            return None;
        }
        // With CLONE_NEWPID the first entry is the pid in the new namespace,
        // which must be 1 since that namespace has no init yet (EINVAL).
        let newpid = flags & libc::CLONE_NEWPID as u64 != 0;
        if read && (tids.iter().any(|tid| *tid < 1) || (newpid && tids[0] != 1)) {
            return None;
        }
        // Choosing a pid takes CAP_SYS_ADMIN or CAP_CHECKPOINT_RESTORE over
        // the namespace, and a caller with neither in its effective set gets
        // EPERM. A set that cannot be read counts as privileged, so the
        // refusal below still guards Detcore's state.
        const CAP_SYS_ADMIN: u32 = 21;
        const CAP_CHECKPOINT_RESTORE: u32 = 40;
        let thread = guest.thread_state();
        let status = format!(
            "/proc/{}/task/{}/status",
            thread.detpid.expect("detpid unset"),
            thread.dettid
        );
        // Only where host tasks describe guest threads: elsewhere (KVM) that
        // file is an unrelated host task's, so the set counts as unread.
        let host_readable = matches!(witness, super::chosen_ids::FaultWitness::HostMaps(_));
        let capabilities = host_readable
            .then(|| std::fs::read_to_string(status).ok())
            .flatten()
            .and_then(|status| {
                status
                    .lines()
                    .find_map(|line| line.strip_prefix("CapEff:"))
                    .and_then(|mask| u64::from_str_radix(mask.trim(), 16).ok())
            });
        let pid_capabilities = (1u64 << CAP_SYS_ADMIN) | (1u64 << CAP_CHECKPOINT_RESTORE);
        if capabilities.is_some_and(|mask| mask & pid_capabilities == 0) {
            return None;
        }
        // From a nested PID namespace the array names pids at several levels,
        // which Detcore does not translate for this: refuse any such call.
        if guest.thread_state().nested_pid_namespace {
            return Some(Err(self
                .refuse_nested_pid(
                    guest,
                    reverie::syscalls::Sysno::clone3,
                    "clone3 set_tid names pids in a namespace Detcore does not translate",
                )
                .await));
        }
        // The array runs from the new task's namespace outwards, so the
        // caller's (the container's) pid is entry 0, or entry 1 with
        // CLONE_NEWPID. Entries after it name pids in the namespaces holding
        // Hermit's container, which Detcore does not track.
        if set_tid_size <= u64::from(newpid) {
            return None;
        }
        if !read {
            return Some(
                self.refuse_unchecked_set_tid(
                    guest,
                    "clone3 set_tid's array cannot be read with the guest's own access",
                )
                .await,
            );
        }
        let tid = tids[usize::from(newpid)];
        if !crate::tool_global::thread_id_refused(guest, DetTid::from_raw(tid)).await {
            return None;
        }
        let message = format!(
            "hermit: clone3 set_tid asks for id {tid}, which an earlier task of this run had; \
             Detcore keeps per-task state by that id and cannot give it to a new task \
             (https://github.com/rrnewton/hermit/issues/4370)"
        );
        tracing::error!(
            "[detcore, dtid {}] {}",
            guest.thread_state().dettid,
            message
        );
        if guest.config().panic_on_unsupported_syscalls {
            use std::io::Write as _;
            let _ = writeln!(crate::util::RetryingStderr, "{message}");
        }
        Some(
            self.refuse_unserviceable_operation(
                guest,
                reverie::syscalls::Sysno::clone3,
                Errno::EEXIST,
            )
            .await,
        )
    }

    /// Refuse a `clone3` whose `set_tid` Detcore cannot check against the
    /// run's earlier tasks, because `what` cannot be read with the guest's own
    /// access while the kernel may read it: the conservative side, since a
    /// reused id would merge two tasks' state in Detcore. With
    /// `--allow-unsupported-syscalls` the call fails with `EFAULT`.
    async fn refuse_unchecked_set_tid<G: Guest<Self>>(
        &self,
        guest: &mut G,
        what: &str,
    ) -> Result<i64, Error> {
        let message = format!(
            "hermit: {what}, so Detcore cannot check its set_tid against the run's earlier tasks \
             (https://github.com/rrnewton/hermit/issues/4370)"
        );
        tracing::error!(
            "[detcore, dtid {}] {}",
            guest.thread_state().dettid,
            message
        );
        if guest.config().panic_on_unsupported_syscalls {
            use std::io::Write as _;
            let _ = writeln!(crate::util::RetryingStderr, "{message}");
        }
        self.refuse_unserviceable_operation(guest, reverie::syscalls::Sysno::clone3, Errno::EFAULT)
            .await
    }

    /// Refuse by name a call from a nested PID namespace whose pids Detcore
    /// cannot translate (https://github.com/rrnewton/hermit/issues/4155).
    async fn refuse_nested_pid<G: Guest<Self>>(
        &self,
        guest: &mut G,
        sysno: reverie::syscalls::Sysno,
        reason: &str,
    ) -> Error {
        tracing::error!(
            "[detcore, dtid {}] {} from a nested PID namespace is not supported: {} (https://github.com/rrnewton/hermit/issues/4155)",
            guest.thread_state().dettid,
            sysno,
            reason,
        );
        match self
            .refuse_unserviceable_operation(guest, sysno, Errno::ENOSYS)
            .await
        {
            Err(error) => error,
            Ok(_) => Errno::ENOSYS.into(),
        }
    }

    /// wait4 system call
    /// This is handled by the scheduler and not passed to the record/replay layer.
    // TODO-HUMAN-REVIEW(PR-587): Confirm wait4 rusage canonicalization boundaries.
    pub async fn handle_wait4<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::Wait4,
    ) -> Result<i64, Error> {
        let serial_emulated_wait =
            guest.config().backend.emulates_child_waits && guest.config().sequentialize_threads;
        let mut emulated_wait_consumed = false;
        let dettid = guest.thread_state().dettid;
        let mut rsrc = Resources::new(dettid);
        rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
        rsrc.fyi("wait4");

        validate_wait4_arguments(call.pid(), call.options())?;

        let parent = guest.thread_state().detpid.expect("detpid unset");
        // A nested caller names its children by its own namespace's pids
        // (https://github.com/rrnewton/hermit/issues/4090). Its process-group
        // ids are not translated yet, nor are emulated waits.
        let nested = guest.thread_state().nested_pid_namespace;
        if nested && (call.pid() == 0 || call.pid() < -1 || serial_emulated_wait) {
            return Err(self
                .refuse_nested_pid(
                    guest,
                    reverie::syscalls::Sysno::wait4,
                    "a process-group wait, or a wait on a backend that emulates child waits",
                )
                .await);
        }
        let named_child = if call.pid() > 0 && nested {
            match crate::tool_global::guest_pid(guest, call.pid()).await {
                GuestPidAnswer::Task { task, .. } => task,
                // No task of the caller's namespace has that pid, so it is
                // not a child: Linux answers ECHILD.
                GuestPidAnswer::NoSuchPid => return Err(Errno::ECHILD.into()),
                GuestPidAnswer::Untranslatable(reason) => {
                    return Err(self
                        .refuse_nested_pid(guest, reverie::syscalls::Sysno::wait4, &reason)
                        .await);
                }
            }
        } else {
            DetPid::from_raw(call.pid())
        };
        // Stop/continue events need a backend waitability callback. Non-SIGCHLD
        // process clones also remain legacy until backends distinguish
        // PTRACE_EVENT_CLONE from CLONE_THREAD. The common matcher already
        // carries those filters so activation does not require another model.
        let selector = if !wait4_uses_terminal_selector(call.options(), serial_emulated_wait) {
            None
        } else {
            match call.pid() {
                pid if pid > 0 => Some(ChildWaitSelector::Exact(named_child)),
                -1 => Some(ChildWaitSelector::Any),
                0 => process_group(guest, parent)
                    .await
                    .map(ChildWaitSelector::ProcessGroup),
                pid if pid < -1 => Some(ChildWaitSelector::ProcessGroup(DetPid::from_raw(-pid))),
                _ => unreachable!(),
            }
        };
        let spec = selector
            .map(|selector| terminal_child_wait_spec(selector, dettid, call.options().bits()));
        let complete_lineage = guest.config().backend.tracks_process_children;
        let managed_spec = if let Some(spec) = spec {
            let (_, has_child) = ready_child_wait(guest, spec).await;
            (has_child || complete_lineage).then_some(spec)
        } else {
            None
        };

        let value = if call.options().contains(WaitPidFlag::WNOHANG) {
            resource_request(guest, rsrc.clone()).await;
            info!(
                "[dtid {}] Executing non-blocking wait4 in one shot.",
                dettid
            );
            if let Some(spec) = spec {
                'select_child: loop {
                    let (ready, has_child) = ready_child_wait(guest, spec).await;
                    let Some(child) = ready else {
                        break if has_child {
                            0
                        } else if complete_lineage {
                            return Err(Errno::ECHILD.into());
                        } else {
                            guest.inject_with_retry(call).await?
                        };
                    };
                    let _ = await_exact_child_physical_exit(guest, child).await;
                    let exact_call = call.with_pid(
                        self.guest_visible_pid(guest, reverie::syscalls::Sysno::wait4, child)
                            .await?,
                    );
                    loop {
                        let result = if serial_emulated_wait {
                            complete_selected_emulated_wait4(guest, exact_call, child).await
                        } else {
                            guest
                                .inject_with_retry(exact_call)
                                .await
                                .map_err(Error::from)
                        };
                        emulated_wait_consumed =
                            serial_emulated_wait && matches!(result, Ok(value) if value > 0);
                        match result {
                            Ok(value) if value != 0 => break 'select_child value,
                            Ok(_) => yield_once().await,
                            Err(Error::Errno(Errno::ECHILD)) => {
                                let _ = consume_child_wait(guest, child).await;
                                if child_wait_can_retry_after_stale(spec) {
                                    continue 'select_child;
                                }
                                return Err(Errno::ECHILD.into());
                            }
                            Err(error) => return Err(error),
                        }
                    }
                }
            } else {
                guest.inject_with_retry(call).await?
            }
        } else if let Some(spec) = managed_spec {
            {
                // The ptrace backend must block ordinary signals until child
                // readiness is resolved. DBT already delays application signal
                // delivery while this callback is active, and replacing its
                // application mask here also hides those signals from
                // rt_sigpending. Read that mask without changing it instead.
                let blocked_mask = blocked_signal_mask();
                let mut stack = guest.stack().await;
                let blocked_mask_addr = stack.push(blocked_mask);
                let old_mask_addr = stack.reserve::<KernelSigset>();
                let action_addr = stack.reserve::<KernelSigaction>();
                let _mask_guard = stack.commit()?;
                let guest_signal_mask =
                    block_signals_for_disposition(guest, blocked_mask_addr, old_mask_addr).await?;
                let inspect_signal_action = guest
                    .config()
                    .backend
                    .requires_thread_directed_process_signals;

                let poll_call = call.with_options(call.options() | WaitPidFlag::WNOHANG);
                let mut pending_signal = None;
                let result: Result<i64, Error> = loop {
                    let status = wait_for_child_lifecycle(guest, spec).await;
                    if pending_signal.is_none() {
                        pending_signal = wait_signal_disposition(
                            guest,
                            status,
                            &guest_signal_mask,
                            action_addr,
                            inspect_signal_action,
                        )
                        .await?;
                    }
                    let (ready, has_child) = ready_child_wait(guest, spec).await;
                    if let Some(child) = ready {
                        let _ = await_exact_child_physical_exit(guest, child).await;
                        let result = if serial_emulated_wait {
                            complete_selected_emulated_wait4(guest, call, child).await
                        } else {
                            match self
                                .guest_visible_pid(guest, reverie::syscalls::Sysno::wait4, child)
                                .await
                            {
                                Ok(pid) => guest
                                    .inject_with_retry(call.with_pid(pid))
                                    .await
                                    .map_err(Error::from),
                                Err(error) => Err(error),
                            }
                        };
                        emulated_wait_consumed =
                            serial_emulated_wait && matches!(result, Ok(value) if value > 0);
                        match result {
                            Ok(value) => break Ok(value),
                            Err(Error::Errno(Errno::ECHILD)) => {
                                let _ = consume_child_wait(guest, child).await;
                                if child_wait_can_retry_after_stale(spec) {
                                    let (next_ready, _) = ready_child_wait(guest, spec).await;
                                    if stale_any_wait_must_interrupt(
                                        pending_signal.is_some(),
                                        next_ready,
                                    ) {
                                        break interrupted_child_wait_result(
                                            guest,
                                            call,
                                            pending_signal.expect("signal checked above"),
                                        )
                                        .await;
                                    }
                                    continue;
                                }
                                break Err(Errno::ECHILD.into());
                            }
                            Err(error) => break Err(error),
                        }
                    }
                    if !has_child {
                        break Err(Errno::ECHILD.into());
                    }
                    if serial_emulated_wait {
                        // A broad backend poll can become consuming while the
                        // owner callback is still publishing logical/CPU state.
                        // Only a selected exact identity may cross that boundary.
                        if let Some(disposition) = pending_signal {
                            break interrupted_child_wait_result(guest, call, disposition).await;
                        }
                        continue;
                    }
                    match guest.inject(poll_call).await {
                        Ok(value) => {
                            if value > 0 {
                                break Ok(value);
                            }
                            if let Some(disposition) = pending_signal {
                                break interrupted_child_wait_result(guest, call, disposition)
                                    .await;
                            }
                        }
                        Err(errno) => break Err(errno.into()),
                    }
                };

                restore_signals_after_disposition(guest, old_mask_addr).await?;
                result?
            }
        } else {
            // wait4 is a scheduler poll, not a record/replay data read (see doc above),
            // so it is not routed through the record/replay subtool.
            retry_nonblocking_syscall(guest, call, rsrc, None).await?
        };
        // The kernel answered in the caller's namespace; the guest gets that
        // pid, and Detcore's bookkeeping the task it names.
        let reaped = if value > 0 {
            self.task_of_guest_pid(guest, reverie::syscalls::Sysno::wait4, value as i32)
                .await?
        } else {
            DetPid::from_raw(value as i32)
        };
        let consumed_termination = if emulated_wait_consumed || value <= 0 {
            false
        } else if let Some(status) = call.wstatus() {
            wait_status_is_termination(guest.memory().read_value(status)?)
        } else if !call
            .options()
            .intersects(WaitPidFlag::WUNTRACED | WaitPidFlag::WCONTINUED)
        {
            // Without them, wait4 reports only a child that terminated. (The
            // exited child's CPU time is recorded where its own Tool runs,
            // which on the in-guest backends is not the parent's, so it
            // cannot tell; https://github.com/rrnewton/hermit/issues/4266.)
            true
        } else {
            // A stop or continue report leaves the child running; once it
            // has exited, the report was its termination.
            guest
                .thread_state()
                .has_exited_child_process_cpu_time(reaped)
                || matches!(
                    crate::tool_global::exact_child_wait_state(guest, reaped).await,
                    ExactChildWaitState::LogicallyExited
                        | ExactChildWaitState::PhysicalExitPending
                        | ExactChildWaitState::PhysicallyExited
                )
        };
        if consumed_termination {
            guest.thread_state_mut().reap_child_process_cpu_time(reaped);
            let _ = consume_child_wait(guest, reaped).await;
        }
        if value > 0
            && let Some(rusage) = call.rusage()
        {
            // Host CPU and scheduling counters are not deterministic.
            let usage: libc::rusage = unsafe { std::mem::zeroed() };
            guest.memory().write_value(rusage, &usage)?;
        }
        Ok(value)
    }

    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(#274): Review waitid polling and compatibility boundaries.
    // TODO-HUMAN-REVIEW(#2246): Review waitid progress and child-ready signal precedence.
    /// waitid system call
    /// This is handled by the scheduler and not passed to the record/replay layer.
    pub async fn handle_waitid<G: Guest<Self>>(
        &self,
        guest: &mut G,
        mut call: syscalls::Waitid,
    ) -> Result<i64, Error> {
        // A backend that emulates child waits (today KVM) can delegate ordered
        // user copyout to itself on the serial path. Enter before the legacy
        // NULL rejection and whole-siginfo writes; ptrace, DBT and
        // nonsequential execution retain their existing path.
        if guest.config().backend.emulates_child_waits && guest.config().sequentialize_threads {
            // Its selector reads the guest's pid as a DetPid
            // (`emulated_waitid::handle`), so a nested caller is refused by name
            // (https://github.com/rrnewton/hermit/issues/4155).
            if guest.thread_state().nested_pid_namespace {
                return Err(self
                    .refuse_nested_pid(
                        guest,
                        reverie::syscalls::Sysno::waitid,
                        "a wait on a backend that emulates child waits",
                    )
                    .await);
            }
            return emulated_waitid::handle(guest, call).await;
        }
        // A nested caller names its children by its own namespace's pids
        // (https://github.com/rrnewton/hermit/issues/4090); its process-group
        // ids are not translated yet.
        let nested = guest.thread_state().nested_pid_namespace;
        if nested && call.which() == libc::P_PGID as i32 {
            return Err(self
                .refuse_nested_pid(
                    guest,
                    reverie::syscalls::Sysno::waitid,
                    "a process-group wait",
                )
                .await);
        }
        let named_child = if nested && call.which() == libc::P_PID as i32 && call.pid() > 0 {
            match crate::tool_global::guest_pid(guest, call.pid()).await {
                GuestPidAnswer::Task { task, .. } => task,
                GuestPidAnswer::NoSuchPid => return Err(Errno::ECHILD.into()),
                GuestPidAnswer::Untranslatable(reason) => {
                    return Err(self
                        .refuse_nested_pid(guest, reverie::syscalls::Sysno::waitid, &reason)
                        .await);
                }
            }
        } else {
            DetPid::from_raw(call.pid())
        };
        let dettid = guest.thread_state().dettid;
        let mut rsrc = Resources::new(dettid);
        rsrc.insert(ResourceID::InternalIOPolling, Permission::W);
        rsrc.fyi("waitid");

        let event_options = libc::WEXITED | libc::WSTOPPED | libc::WCONTINUED;
        let allowed_options = event_options
            | libc::WNOHANG
            | libc::WNOWAIT
            | libc::__WNOTHREAD
            | libc::__WALL
            | libc::__WCLONE;
        if call.options() & event_options == 0 || call.options() & !allowed_options != 0 {
            return Err(Errno::EINVAL.into());
        }

        // POSIX requires non-null infop. Linux accepts null, but that form can
        // expose host rusage and requires backend-neutral scratch memory for
        // deterministic polling. Reject it uniformly instead of diverging or
        // panicking on DBT's unsupported scratch stack.
        if call.info().is_none() {
            return Err(Errno::EFAULT.into());
        }

        // Keep clone-class waits on the legacy path until ptrace and KVM both
        // register non-SIGCHLD clone children as processes rather than threads.
        let terminal_events_only = call.options() & libc::WEXITED != 0
            && call.options() & (libc::WSTOPPED | libc::WCONTINUED | libc::__WCLONE | libc::__WALL)
                == 0;

        // The parked nonterminal path still uses kernel polling. Preserve its
        // P_PGID(0) entry snapshot until backend lifecycle events replace it.
        if !terminal_events_only && call.which() == libc::P_PGID as i32 && call.pid() == 0 {
            call = call.with_pid(snapshot_process_group(guest.pid())?);
        }

        // A blocking waitid on an O_NONBLOCK pidfd must return EAGAIN rather
        // than being converted to WNOHANG. Acquire the scheduler resource first,
        // then snapshot fdinfo and issue the one-shot wait without another yield.
        let pidfd_nonblocking =
            if call.which() == libc::P_PIDFD as i32 && call.options() & libc::WNOHANG == 0 {
                resource_request(guest, rsrc.clone()).await;
                guest_fd_status_flags(guest.pid(), call.pid())? & libc::O_NONBLOCK != 0
            } else {
                false
            };
        if call.which() == libc::P_PIDFD as i32
            && call.options() & libc::WNOHANG == 0
            && !pidfd_nonblocking
        {
            // Polling a numeric pidfd cannot preserve Linux's held file
            // reference if another thread closes and reuses the descriptor.
            // Reject the blocking form until Detcore can retain that identity.
            return Err(Errno::EOPNOTSUPP.into());
        }
        let info = call
            .info()
            .expect("waitid infop checked above")
            .cast::<GuestSiginfo>();

        // Unlike wait4, waitid returns zero both when it reports a child event and
        // when WNOHANG finds nothing. Polling must inspect si_pid to distinguish
        // those cases.
        // Known limitation: without backend-neutral scratch memory, an invalid
        // non-null infop faults on the first physical poll rather than after a
        // child becomes waitable.
        // The lifecycle scheduler currently models terminal child events for
        // exact and any-child selectors. Group membership and stop/continue
        // state remain on the legacy kernel-polling path.
        let terminal_spec = if terminal_events_only {
            let selector = match call.which() {
                which if which == libc::P_PID as i32 => Some(ChildWaitSelector::Exact(named_child)),
                which if which == libc::P_ALL as i32 => Some(ChildWaitSelector::Any),
                which if which == libc::P_PGID as i32 => {
                    let group = if call.pid() == 0 {
                        process_group(guest, guest.thread_state().detpid.expect("detpid unset"))
                            .await
                    } else {
                        Some(DetPid::from_raw(call.pid()))
                    };
                    group.map(ChildWaitSelector::ProcessGroup)
                }
                _ => None,
            };
            selector.map(|selector| terminal_child_wait_spec(selector, dettid, call.options()))
        } else {
            None
        };
        let complete_lineage = guest.config().backend.tracks_process_children;
        let managed_terminal_spec = if let Some(spec) = terminal_spec {
            let (_, has_child) = ready_child_wait(guest, spec).await;
            (has_child || complete_lineage).then_some(spec)
        } else {
            None
        };

        if call.options() & libc::WNOHANG != 0 || pidfd_nonblocking {
            if !pidfd_nonblocking {
                resource_request(guest, rsrc).await;
            }
            info!(
                "[dtid {}] Executing non-blocking waitid in one shot.",
                dettid
            );
            'select_child: loop {
                let selected = if let Some(spec) = terminal_spec {
                    let (ready, has_child) = ready_child_wait(guest, spec).await;
                    if ready.is_none() && has_child {
                        guest.memory().write_value(info, &GuestSiginfo::zeroed())?;
                        return Ok(0);
                    }
                    if ready.is_none() && complete_lineage {
                        return Err(Errno::ECHILD.into());
                    }
                    ready
                } else {
                    None
                };
                if let Some(child) = selected {
                    let _ = await_exact_child_physical_exit(guest, child).await;
                }
                let effective_call = match selected {
                    Some(child) => call.with_which(libc::P_PID as i32).with_pid(
                        self.guest_visible_pid(guest, reverie::syscalls::Sysno::waitid, child)
                            .await?,
                    ),
                    None => call,
                };
                loop {
                    guest.memory().write_value(info, &GuestSiginfo::zeroed())?;
                    let value = match guest.inject_with_retry(effective_call).await {
                        Ok(value) => value,
                        Err(Errno::ECHILD) if selected.is_some() => {
                            let child = selected.expect("selected child checked above");
                            let _ = consume_child_wait(guest, child).await;
                            if terminal_spec.is_some_and(child_wait_can_retry_after_stale) {
                                continue 'select_child;
                            }
                            return Err(Errno::ECHILD.into());
                        }
                        Err(errno) => return Err(errno.into()),
                    };
                    let info_value: GuestSiginfo = guest.memory().read_value(info)?;
                    let child_pid = info_value.pid();
                    if child_pid == 0 && selected.is_some() {
                        yield_once().await;
                        continue;
                    }
                    let consumed = child_pid != 0
                        && call.options() & libc::WNOWAIT == 0
                        && waitid_code_is_termination(info_value.code());
                    let child = self
                        .task_of_guest_pid(guest, reverie::syscalls::Sysno::waitid, child_pid)
                        .await?;
                    let result = finish_waitid_result(guest, call, value, info_value.0, child)?;
                    if consumed {
                        let _ = consume_child_wait(guest, child).await;
                    }
                    return Ok(result);
                }
            }
        }

        {
            // A signal can arrive after the scheduler wakes this logical wait but
            // before the zero-timeout kernel probe that resolves Linux's
            // child-ready-versus-interrupt precedence. The ptrace backend blocks
            // ordinary signals across that probe, then restores the guest's exact
            // mask before returning. DBT reads the mask without replacing it because
            // DynamoRIO already delays application delivery while this callback runs.
            // The tracer's private preemption signal must remain unblocked.
            let blocked_mask = blocked_signal_mask();
            let mut stack = guest.stack().await;
            let blocked_mask_addr = stack.push(blocked_mask);
            let old_mask_addr = stack.reserve::<KernelSigset>();
            let action_addr = stack.reserve::<KernelSigaction>();
            let _mask_guard = stack.commit()?;
            let guest_signal_mask =
                block_signals_for_disposition(guest, blocked_mask_addr, old_mask_addr).await?;
            let inspect_signal_action = guest
                .config()
                .backend
                .requires_thread_directed_process_signals;

            let poll_call = call.with_options(call.options() | libc::WNOHANG);
            let mut pending_signal = None;
            let result: Result<i64, Error> = loop {
                // Match the polling protocol used by wait4: the first request with
                // poll_attempt zero establishes an ordinary runnable turn, while later
                // nonzero attempts receive the scheduler's poller backoff. Omitting the
                // first request starts directly as a poller and can keep the run queue
                // nonempty forever, preventing logical time from reaching a pending
                // signal's deadline.
                //
                // Do not return on Signaled yet. Linux lets an already-waitable child
                // status win over an interrupt, so the zero-timeout kernel probe below
                // remains authoritative when readiness and a signal coincide.
                let managed_spec = managed_terminal_spec;
                // Both ways of parking inside waitid -- the scheduler-managed child
                // wait and the legacy kernel-polling loop -- can now be resumed with
                // the signals that woke the thread, so both consult the guest mask.
                let status = if let Some(spec) = managed_spec {
                    wait_for_child_lifecycle(guest, spec).await
                } else {
                    resource_request(guest, rsrc.clone()).await
                };
                if pending_signal.is_none() {
                    pending_signal = wait_signal_disposition(
                        guest,
                        status,
                        &guest_signal_mask,
                        action_addr,
                        inspect_signal_action,
                    )
                    .await?;
                }
                let (ready, has_child) = if let Some(spec) = managed_spec {
                    ready_child_wait(guest, spec).await
                } else {
                    (None, true)
                };
                if let Some(child) = ready {
                    let _ = await_exact_child_physical_exit(guest, child).await;
                    if let Err(error) = guest.memory().write_value(info, &GuestSiginfo::zeroed()) {
                        break Err(error.into());
                    }
                    let pid = match self
                        .guest_visible_pid(guest, reverie::syscalls::Sysno::waitid, child)
                        .await
                    {
                        Ok(pid) => pid,
                        Err(error) => break Err(error),
                    };
                    let exact_call = call.with_which(libc::P_PID as i32).with_pid(pid);
                    match guest.inject_with_retry(exact_call).await {
                        Ok(value) => {
                            let info_value = match guest.memory().read_value(info) {
                                Ok(value) => value,
                                Err(error) => break Err(error.into()),
                            };
                            let reported = match self
                                .task_of_guest_pid(
                                    guest,
                                    reverie::syscalls::Sysno::waitid,
                                    info_value.pid(),
                                )
                                .await
                            {
                                Ok(task) => task,
                                Err(error) => break Err(error),
                            };
                            break finish_waitid_result(guest, call, value, info_value.0, reported);
                        }
                        Err(Errno::ECHILD) => {
                            let _ = consume_child_wait(guest, child).await;
                            if managed_spec.is_some_and(child_wait_can_retry_after_stale) {
                                let (next_ready, _) =
                                    ready_child_wait(guest, managed_spec.expect("managed spec"))
                                        .await;
                                if stale_any_wait_must_interrupt(
                                    pending_signal.is_some(),
                                    next_ready,
                                ) {
                                    break interrupted_child_wait_result(
                                        guest,
                                        call,
                                        pending_signal.expect("signal checked above"),
                                    )
                                    .await;
                                }
                                continue;
                            }
                            break Err(Errno::ECHILD.into());
                        }
                        Err(errno) => break Err(errno.into()),
                    }
                }
                if managed_spec.is_some() && !has_child {
                    break Err(Errno::ECHILD.into());
                }

                if let Err(error) = guest.memory().write_value(info, &GuestSiginfo::zeroed()) {
                    break Err(error.into());
                }
                let result = guest.inject(poll_call).await;
                match result {
                    Ok(value) => {
                        let info_value = match guest.memory().read_value(info) {
                            Ok(value) => value,
                            Err(error) => break Err(error.into()),
                        };
                        // waitid writes the SIGCHLD variant of siginfo_t. A zeroed
                        // structure is used only for the no-event WNOHANG result.
                        let child_pid = info_value.pid();
                        match exact_wait_poll_decision(
                            child_pid != 0,
                            pending_signal.is_some(),
                            None,
                        ) {
                            ExactWaitPollDecision::ChildReady => {
                                let reported = match self
                                    .task_of_guest_pid(
                                        guest,
                                        reverie::syscalls::Sysno::waitid,
                                        child_pid,
                                    )
                                    .await
                                {
                                    Ok(task) => task,
                                    Err(error) => break Err(error),
                                };
                                break finish_waitid_result(
                                    guest,
                                    call,
                                    value,
                                    info_value.0,
                                    reported,
                                );
                            }
                            ExactWaitPollDecision::Interrupted => {
                                break interrupted_child_wait_result(
                                    guest,
                                    call,
                                    pending_signal.expect("signal checked above"),
                                )
                                .await;
                            }
                            ExactWaitPollDecision::Retry => {}
                            ExactWaitPollDecision::AwaitPhysicalExit
                            | ExactWaitPollDecision::ReapAfterLogicalExit => unreachable!(),
                        }
                        if managed_spec.is_some() {
                            if !has_child {
                                break Ok(value);
                            }
                            continue;
                        }
                        rsrc.poll_attempt += 1;
                        trace!(
                            "Retry #{} for waitid because no child state is ready",
                            rsrc.poll_attempt
                        );
                        record_retry_event(guest, poll_call).await;
                    }
                    Err(Errno::ERESTARTSYS) if pending_signal.is_some() => {
                        break Err(Errno::EINTR.into());
                    }
                    Err(errno) => break Err(errno.into()),
                }
            };

            restore_signals_after_disposition(guest, old_mask_addr).await?;
            if result.is_ok() && call.options() & libc::WNOWAIT == 0 {
                let info_value: GuestSiginfo = guest.memory().read_value(info)?;
                let child_pid = info_value.pid();
                if child_pid != 0 && waitid_code_is_termination(info_value.code()) {
                    let child = self
                        .task_of_guest_pid(guest, reverie::syscalls::Sysno::waitid, child_pid)
                        .await?;
                    let _ = consume_child_wait(guest, child).await;
                }
            }
            result
        }
    }

    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(#546)
    /// Accept valid affinity masks without changing the host scheduler.
    /// Under `--virtual-cpus` the mask is checked and kept as Linux does
    /// (`virtual_sched_setaffinity`); Hermit's historical single CPU accepts
    /// any readable mask and stays CPU 0.
    pub async fn handle_sched_setaffinity<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::SchedSetaffinity,
    ) -> Result<i64, Error> {
        if let Some(cpus) = self.cfg.virtual_cpus {
            return self
                .virtual_sched_setaffinity(guest, call, cpus.get())
                .await;
        }
        let size_bytes = call.len() as usize;
        if size_bytes == 0 {
            return Err(Errno::EINVAL.into());
        }

        let mask = call.mask().ok_or(Errno::EFAULT)?;
        let mask: Addr<u8> = mask.cast();
        let mut requested = [0u8; VIRTUAL_CPUSET_BYTES];
        let bytes_to_read = size_bytes.min(VIRTUAL_CPUSET_BYTES);
        guest
            .memory()
            .read_exact(mask, &mut requested[..bytes_to_read])?;
        info!(
            "Suppressing sched_setaffinity mask {:?}; affinity remains virtual CPU 0",
            requested
        );
        Ok(0)
    }

    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(#546)
    /// Report that we are on cpu 0, irrespective of what physical CPU we are on.
    ///
    /// Linux's `sched_getaffinity` accepts any length whose bits cover
    /// `nr_cpu_ids` (one, for Hermit's single virtual CPU) and that is a
    /// multiple of `sizeof(long)`, copies `min(len, cpumask_size())` bytes and
    /// returns that count. Detcore's mask is `VIRTUAL_CPUSET_BYTES` long
    /// (`kernel_max` 127), so an 8-byte set, which `CPU_ALLOC` gives for the
    /// one CPU that `sysconf(_SC_NPROCESSORS_CONF)` reports, receives its
    /// first 8 bytes (<https://github.com/rrnewton/hermit/issues/4160>).
    /// Under `--virtual-cpus` it is the named task's mask over the machine's
    /// CPUs (`virtual_sched_getaffinity`).
    pub async fn handle_sched_getaffinity<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::SchedGetaffinity,
    ) -> Result<i64, Error> {
        if let Some(cpus) = self.cfg.virtual_cpus {
            return self
                .virtual_sched_getaffinity(guest, call, cpus.get())
                .await;
        }
        let size_bytes: usize = call.len() as usize;
        if size_bytes == 0 || !size_bytes.is_multiple_of(std::mem::size_of::<libc::c_ulong>()) {
            return Err(Errno::EINVAL.into());
        }
        let copied = size_bytes.min(VIRTUAL_CPUSET_BYTES);

        // N.B. we can't use an opaque, type-safe representation such as
        // nix::sched::CpuSet currently.  The problem is that the
        // SchedGetAffinity syscall treats this field as a u64.
        let mut cpu_set = [0u8; VIRTUAL_CPUSET_BYTES];
        cpu_set[0] = 1;

        info!(
            "Suppressing sched_getaffinity and returning {}-byte virtualized result, {:?}",
            copied,
            &cpu_set[..copied]
        );
        if let Some(mask) = call.mask() {
            let mask: AddrMut<u8> = mask.cast();
            guest.memory().write_exact(mask, &cpu_set[..copied])?;
            // From the man page:
            // > On success, the raw sched_getaffinity() system call returns the size (in bytes) of
            // > the cpumask_t data type that is used internally by the kernel to represent the CPU
            // > set bit mask.
            // Linux returns the bytes it copied, the smaller of that size and the caller's.
            Ok(copied as i64)
        } else {
            Err(Error::Errno(Errno::EFAULT))
        }
    }

    /// sched_getparam under Hermit. Detcore replaces the Linux scheduler with its
    /// own deterministic one, so a thread's Linux scheduling parameters are
    /// inert. Report a fixed SCHED_OTHER priority of 0. The value is emulated
    /// (never injected), so it is identical across --verify runs and
    /// record/replay.
    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(#720)
    pub async fn handle_sched_getparam<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::SchedGetparam,
    ) -> Result<i64, Error> {
        if let Some(param) = call.param() {
            write_sched_getparam(&mut guest.memory(), param)?;
        }
        Ok(0)
    }

    /// sched_rr_get_interval under Hermit. The round-robin quantum is a property
    /// of the Linux scheduler, which Detcore does not use, so report a fixed zero
    /// interval. Being a constant, it is deterministic across --verify and
    /// record/replay.
    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(#720)
    pub async fn handle_sched_rr_get_interval<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::SchedRrGetInterval,
    ) -> Result<i64, Error> {
        if let Some(tp) = call.tp() {
            let t = Timespec {
                tv_sec: 0,
                tv_nsec: 0,
            };
            guest.memory().write_value(tp, &t)?;
        }
        Ok(0)
    }

    /// sched_getattr under Hermit. Detcore replaces the Linux scheduler with its
    /// own deterministic one, so a thread's Linux scheduling attributes are inert.
    /// Report a fixed SCHED_OTHER policy with zeroed nice/priority/flags. The
    /// value is emulated (never injected), so it is identical across --verify runs
    /// and record/replay. Re-enables `chrt` under --strict.
    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(#791)
    pub async fn handle_sched_getattr<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::SchedGetattr,
    ) -> Result<i64, Error> {
        // `flags` is reserved and must be zero; the kernel rejects anything else.
        if call.flags() != 0 {
            return Err(Errno::EINVAL.into());
        }
        // The caller must provide room for at least the base sched_attr (VER0).
        let attr_size = std::mem::size_of::<libc::sched_attr>();
        if (call.size() as usize) < attr_size {
            return Err(Errno::EINVAL.into());
        }
        let attr = call.attr().ok_or(Errno::EINVAL)?;
        // SAFETY: sched_attr is a plain-old-data struct; an all-zero bit pattern is
        // a valid SCHED_OTHER descriptor (nice/priority/flags/runtime/... all 0).
        let mut sa: libc::sched_attr = unsafe { std::mem::zeroed() };
        sa.size = attr_size as u32;
        sa.sched_policy = libc::SCHED_OTHER as u32;
        // SAFETY: reinterpret the POD struct as its raw bytes to copy it into the
        // guest's buffer.
        let bytes = unsafe {
            std::slice::from_raw_parts(&sa as *const libc::sched_attr as *const u8, attr_size)
        };
        let dst: AddrMut<u8> = attr.cast();
        guest.memory().write_exact(dst, bytes)?;
        info!(
            "Emulating sched_getattr(pid={}): fixed SCHED_OTHER, nice 0, priority 0",
            call.pid()
        );
        Ok(0)
    }

    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(PR-841): Review virtual sched_setattr no-op policy.
    /// Linux scheduler attributes cannot affect Detcore's replacement
    /// scheduler, so a *well-formed* request is accepted as a deterministic
    /// no-op, matching the existing sched_setscheduler and sched_setparam
    /// policy.
    ///
    /// Suppressing the effect is not the same as accepting arguments Linux
    /// refuses, nor as refusing arguments Linux accepts. Both directions are
    /// guest-visible: a probe that expects EINVAL and sees success takes the
    /// wrong branch, and so does one that expects success and sees E2BIG.
    ///
    /// The order below is the kernel's, and it is guest-visible when two
    /// arguments are wrong at once, because the kernel returns the *first*
    /// applicable error. `sched_setattr()` screens `uattr`, `pid` and `flags`
    /// together; `sched_copy_attr()` then handles the size, the trailing bytes
    /// and the util-clamp size rule; the signed-policy test follows; the target
    /// pid is resolved *there*, in the middle; and only then does
    /// `__sched_setscheduler()` judge the policy, the flags, the priority and
    /// the deadline parameters. Putting any of that last group before the pid
    /// lookup makes a request against a nonexistent pid report EINVAL where
    /// Linux reports ESRCH.
    ///
    /// # Determinism
    ///
    /// Every check is a pure function of the guest's own arguments. The one
    /// piece of state consulted is the pid lookup, which asks the scheduler's
    /// own task table via `thread_is_live` -- Detcore state, replayed
    /// identically -- rather than the host's process table, which would leak
    /// unrelated host processes into a guest-visible answer.
    ///
    /// Specifically NOT `tool_global::resolve_kill_targets`, which
    /// models `kill(2)` and so recognises only thread-group leaders; asking it
    /// this question reports ESRCH for a live non-leader thread.
    ///
    /// # Deliberately not emulated
    ///
    /// Three behaviours are excluded, under one rule: **an answer that depends
    /// on the host's kernel configuration or the caller's privileges is not
    /// reproduced, because a deterministic sandbox must not vary with the
    /// machine underneath it.** Each was measured natively and would differ on
    /// a differently-built or differently-privileged host:
    ///
    /// * EPERM for a real-time priority, a SCHED_DEADLINE admission, or a
    ///   negative nice, which depends on `CAP_SYS_NICE` and `RLIMIT_RTPRIO`.
    /// * EOPNOTSUPP for util-clamp on a VER1 buffer, which depends on
    ///   `CONFIG_UCLAMP_TASK`.
    /// * The `sysctl_sched_dl_period_{min,max}` bound on SCHED_DEADLINE
    ///   periods, which is runtime-tunable.
    ///
    /// In all three Hermit accepts the request as the same no-op as any other
    /// well-formed one. The same rule is why SCHED_EXT (policy 7) is accepted
    /// unconditionally even though `valid_policy()` admits it only with
    /// `CONFIG_SCHED_CLASS_EXT`: picking one answer keeps the sandbox stable
    /// across hosts, and accepting is the choice consistent with suppressing
    /// the effect rather than refusing the request.
    ///
    /// The bracketed regression test in `hermit-cli/tests/sched_setattr_abi.rs`
    /// compares Hermit against the running kernel case by case, and therefore
    /// deliberately omits exactly these cases -- including them would make its
    /// verdict depend on the host it runs on.
    pub async fn handle_sched_setattr<G: Guest<Self>>(
        &self,
        guest: &mut G,
        call: syscalls::SchedSetattr,
    ) -> Result<i64, Error> {
        // `if (!uattr || pid < 0 || flags)` -- one clause in the kernel, so all
        // three are EINVAL and none of them is ordered against the others. A
        // null pointer is EINVAL rather than EFAULT because it is refused
        // before any access is attempted.
        if call.flags() != 0 || call.pid() < 0 {
            return Err(Errno::EINVAL.into());
        }
        let attr = call.attr().ok_or(Errno::EINVAL)?;

        // `get_user(size, &uattr->size)` -- the declared size is read before
        // anything else, and a fault here is EFAULT with no store back.
        // `AddrMut` is not `Copy` and `cast` consumes it, so each access below
        // re-derives the address from the syscall argument.
        // A fault reading guest memory is EFAULT for this syscall. The
        // backend's memory layer reports a failed peek as EIO, which is not an
        // errno `sched_setattr` can return, so it is mapped here; measured
        // native, an unmapped `uattr` gives EFAULT.
        let declared: u32 = guest
            .memory()
            .read_value(attr.cast())
            .map_err(|_| Errno::EFAULT)?;

        // Both E2BIG exits below run the kernel's `err_size` path, which stores
        // the kernel's own struct size into `uattr->size` before returning. A
        // guest that reads the field back learns the size it should have sent,
        // which is the entire point of the store; the kernel ignores whether it
        // succeeds, and so do we.
        fn refuse_too_big<S: MemoryAccess>(mut memory: S, attr: AddrMut<libc::c_void>) -> Error {
            let _ = memory.write_value(attr.cast::<u32>(), &SCHED_ATTR_KERNEL_SIZE);
            Errno::E2BIG.into()
        }

        let size = match sched_attr_effective_size(declared) {
            Ok(size) => size,
            Err(()) => {
                let back = call.attr().ok_or(Errno::EINVAL)?;
                return Err(refuse_too_big(guest.memory(), back));
            }
        };

        // `copy_struct_from_user` with a user size past the kernel's struct:
        // every trailing byte must be zero, or the guest is sending a field
        // this kernel does not know and must not silently drop. A fault while
        // scanning is EFAULT and skips the store back -- only the not-all-zero
        // verdict is E2BIG.
        if size > SCHED_ATTR_KERNEL_SIZE {
            let base: AddrMut<u8> = call.attr().ok_or(Errno::EINVAL)?.cast();
            match scan_tail_is_zeroed(
                &guest.memory(),
                base,
                SCHED_ATTR_KERNEL_SIZE as usize,
                (size - SCHED_ATTR_KERNEL_SIZE) as usize,
            ) {
                TailVerdict::AllZero => {}
                TailVerdict::NotZeroed => {
                    let back = call.attr().ok_or(Errno::EINVAL)?;
                    return Err(refuse_too_big(guest.memory(), back));
                }
                TailVerdict::Faulted => return Err(Errno::EFAULT.into()),
            }
        }

        // Copy the interoperable prefix, zero-filling anything the guest's
        // buffer is too short to carry, exactly as `copy_struct_from_user`
        // does for a short read.
        let copied = std::cmp::min(size, SCHED_ATTR_KERNEL_SIZE) as usize;
        let mut raw = [0u8; SCHED_ATTR_KERNEL_SIZE as usize];
        let base: AddrMut<u8> = call.attr().ok_or(Errno::EINVAL)?.cast();
        guest
            .memory()
            .read_exact(base, &mut raw[..copied])
            .map_err(|_| Errno::EFAULT)?;
        let field32 = |offset: usize| -> u32 {
            u32::from_ne_bytes(raw[offset..offset + 4].try_into().expect("4 bytes"))
        };
        let field64 = |offset: usize| -> u64 {
            u64::from_ne_bytes(raw[offset..offset + 8].try_into().expect("8 bytes"))
        };
        let fields = SchedAttrFields {
            policy: field32(SCHED_ATTR_OFF_POLICY),
            sched_flags: field64(SCHED_ATTR_OFF_FLAGS),
            priority: field32(SCHED_ATTR_OFF_PRIORITY),
            runtime: field64(SCHED_ATTR_OFF_RUNTIME),
            deadline: field64(SCHED_ATTR_OFF_DEADLINE),
            period: field64(SCHED_ATTR_OFF_PERIOD),
        };

        // Everything the kernel decides before it resolves the pid.
        validate_sched_attr_before_lookup(size, &fields)?;

        // `find_process_by_pid()` sits here, between the two groups of checks,
        // and the position is guest-visible: a request that is malformed only
        // in a way judged below reports ESRCH rather than EINVAL when the pid
        // does not exist. pid 0 means the calling thread, which always exists;
        // otherwise ask the scheduler's own task table, so the answer comes
        // from Detcore's state rather than from the host's process table.
        // `find_task_by_vpid` resolves ANY LIVE TASK, not just a thread-group
        // leader. The kill-target resolver is the wrong question here: it
        // models `kill(2)`, whose first act is to refuse anything that is not a
        // leader, so a perfectly live non-leader thread's tid reported ESRCH.
        // A nested caller names the thread by its own namespace's tid
        // (https://github.com/rrnewton/hermit/issues/4155).
        let named = if call.pid() > 0 && guest.thread_state().nested_pid_namespace {
            match crate::tool_global::guest_pid(guest, call.pid()).await {
                GuestPidAnswer::Task { task, .. } => Some(task),
                GuestPidAnswer::NoSuchPid => None,
                GuestPidAnswer::Untranslatable(reason) => {
                    return Err(self
                        .refuse_nested_pid(guest, reverie::syscalls::Sysno::sched_setattr, &reason)
                        .await);
                }
            }
        } else {
            Some(DetTid::from_raw(call.pid()))
        };
        if call.pid() != 0 {
            match named {
                Some(task) if thread_is_live(guest, task).await => {}
                _ => return Err(Errno::ESRCH.into()),
            }
        }

        // And everything `__sched_setscheduler` decides after it.
        validate_sched_attr_after_lookup(&fields)?;

        info!(
            "Suppressing sched_setattr(pid={}, flags={}); Linux scheduler attributes are virtual",
            call.pid(),
            call.flags()
        );
        Ok(0)
    }

    /// ioprio_set under Hermit. Detcore serializes guest threads onto one virtual
    /// CPU, so the block-layer I/O scheduling class and priority cannot change
    /// guest-visible computation. Accept and suppress the request as a
    /// deterministic no-op success, mirroring how sched_setaffinity is handled.
    /// Re-enables `ionice` under --strict.
    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(#791)
    pub async fn handle_ioprio_set<G: Guest<Self>>(
        &self,
        _guest: &mut G,
        call: syscalls::IoprioSet,
    ) -> Result<i64, Error> {
        info!(
            "Suppressing ioprio_set(which={}, who={}, priority={}); I/O priority is virtual",
            call.which(),
            call.who(),
            call.priority()
        );
        Ok(0)
    }

    /// ioprio_get under Hermit. I/O priority is inert under Detcore's serialized
    /// scheduler, so process queries observe the fixed raw IOPRIO_CLASS_NONE
    /// value while group/user queries observe the effective SCHED_OTHER default
    /// of IOPRIO_CLASS_BE/4, without consulting host block-scheduler state.
    // AUTONOMOUS-BOT-IMPLEMENTED
    // TODO-HUMAN-REVIEW(PR-881)
    pub async fn handle_ioprio_get<G: Guest<Self>>(
        &self,
        _guest: &mut G,
        call: syscalls::IoprioGet,
    ) -> Result<i64, Error> {
        let priority = virtual_ioprio(call.which())?;

        info!(
            "Emulating ioprio_get(which={}, who={}): fixed priority {}",
            call.which(),
            call.who(),
            priority
        );
        Ok(priority)
    }
}

/// The one real implementation of [`robust_list::RobustDeathEffects`]: guest
/// memory plus a wake against Detcore's modeled futex waiter pool.
///
/// It exists so the walk itself never mentions `Guest`, and can therefore be
/// unit-tested against fake memory.
struct GuestRobustEffects<'a, G, T> {
    guest: &'a mut G,
    dettid: DetTid,
    staged_wakes: Option<&'a mut Vec<RobustListWake>>,
    /// The words this exit's walks found owned by their dying owner, keyed as
    /// futexes (so two mappings of one shared page are one word), with the
    /// value Linux's walk stores there. Detcore does not store it, so a later
    /// read of the same word, through another entry or another owner's list
    /// in the same group exit, sees this value, as it would after Linux's
    /// store.
    marked: &'a mut HashMap<FutexID, u32>,
    tool: PhantomData<T>,
}

impl<G, T> robust_list::RobustDeathEffects for GuestRobustEffects<'_, G, T>
where
    G: Guest<Detcore<T>>,
    T: RecordOrReplay,
{
    fn read_u64(&mut self, address: usize) -> Option<u64> {
        let at = Addr::<u64>::from_raw(address)?;
        self.guest.memory().read_value::<_, u64>(at).ok()
    }

    fn read_u32(&mut self, address: usize) -> Option<u32> {
        let at = Addr::<u32>::from_raw(address)?;
        let value = self.guest.memory().read_value::<_, u32>(at).ok()?;
        let futexid = self.guest.thread_state().futex_id(address, false);
        Some(self.marked.get(&futexid).copied().unwrap_or(value))
    }

    fn compare_and_swap(
        &mut self,
        address: usize,
        expected: u32,
        desired: u32,
    ) -> robust_list::FutexCasOutcome {
        use robust_list::FutexCasOutcome;

        let Some(read_at) = Addr::<u32>::from_raw(address) else {
            return FutexCasOutcome::Faulted;
        };
        // Detcore never stores the owner word itself. It re-reads the word to
        // decide whether the kernel's retry loop would take another pass, then
        // leaves the replacement to the native task exit, which every
        // [`OwnerDeathPath`] completes before another modeled thread runs.
        let observed = match self.guest.memory().read_value::<_, u32>(read_at) {
            Ok(value) => value,
            Err(_) => return FutexCasOutcome::Faulted,
        };
        let futexid = self.guest.thread_state().futex_id(address, false);
        let observed = self.marked.get(&futexid).copied().unwrap_or(observed);
        if observed != expected {
            return FutexCasOutcome::Changed(observed);
        }
        self.marked.insert(futexid, desired);
        // No other scheduler turn runs until Linux has repeated the owner
        // check and changed the word atomically. Do not perform a separate
        // write here: a process outside Hermit's scheduler can share the
        // mapping and acquire the mutex between this read and that write.
        // Deliberately DEBUG, not INFO: this line carries a raw guest address,
        // and INFO is the surface `--verify-strict` compares.
        debug!(
            "[detcore, dtid {}] robust-list owner death: leaving futex word {:#x} for backend exit cleanup",
            self.dettid, address,
        );
        FutexCasOutcome::Matched
    }

    async fn wake_one(&mut self, address: usize, observed: u32) {
        // glibc always issues robust-mutex futex operations with the shared
        // flag, and so does the kernel's owner-death wake; resolve the same key.
        let futexid = self.guest.thread_state().futex_id(address, false);
        if let Some(wakes) = self.staged_wakes.as_mut() {
            wakes.push(RobustListWake { futex: futexid });
            debug!(
                "[detcore, dtid {}] staged robust-list owner-death wake until physical exit",
                self.dettid,
            );
            return;
        }
        let woken = match futex_action(
            self.guest,
            FutexAction::WakeRequest(1),
            &futexid,
            observed as i32,
            u32::MAX,
        )
        .await
        {
            Some(SchedValue::Value(count)) => count,
            // A FUTEX_LOCK_PI waiter first in the queue stops the wake: Linux's
            // `futex_wake` answers EINVAL, which `handle_futex_death` ignores.
            Some(SchedValue::PiWaiterReached { woken }) => woken,
            // A wake never carries a timeout, and a cancelled RPC wakes nobody.
            Some(SchedValue::TimeOut)
            | Some(SchedValue::Signaled(_))
            | Some(SchedValue::Requeued { .. })
            | Some(SchedValue::PiFutex(_))
            | Some(SchedValue::PiTaken(_))
            | None => 0,
        };
        // Guest-level identities only: dettid, the modeled futex key, and a
        // count. No host pointers and no iteration order leak into this line,
        // which is compared exactly under `--verify-strict`.
        info!(
            "[detcore, dtid {}] robust-list owner death woke {} waiter(s) on futex {:?}",
            self.dettid, woken, futexid,
        );
        let _ = futex_action(
            self.guest,
            FutexAction::WakeFinished(0),
            &futexid,
            observed as i32,
            u32::MAX,
        )
        .await;
    }
}

/// How a thread group's robust-mutex owners die, for
/// `Detcore::read_thread_group_robust_list_wakes`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum OwnerDeath {
    /// exit_group or a fatal signal: every thread exits with its own TID.
    Exit,
    /// A successful execve: the other threads exit with their own TIDs, and the
    /// caller's list is walked under the TID it holds after `de_thread`.
    Exec,
}

/// `Detcore::robust_owner_death_path` for `cfg`.
///
/// The Barrier path needs three properties of a backend: an exit callback that
/// runs before the native exit, a native exit that runs Linux's own robust
/// walk, and a registered host pidfd for every thread, which the scheduler's
/// exited-thread hold polls. `requires_thread_directed_process_signals` is
/// the flag that makes Detcore refuse a thread without host IDs, so it implies
/// the third; today only DBT sets it, and DBT has the other two.
/// `owner_death_path_is_tied_to_the_backends_that_have_its_properties` fails
/// if another backend starts to set it (Claude review of
/// https://github.com/rrnewton/hermit/pull/4277 at 65138a17, N4).
fn owner_death_path(cfg: &Config) -> Option<OwnerDeathPath> {
    if !cfg.sequentialize_threads || cfg.debug_futex_mode != BlockingMode::Precise {
        return None;
    }
    if cfg.backend.runs_exit_robust_list {
        Some(OwnerDeathPath::Kernel)
    } else if cfg.backend.requires_thread_directed_process_signals {
        Some(OwnerDeathPath::Barrier)
    } else {
        None
    }
}

/// How Detcore orders its modeled owner-death wakes after Linux's own walk.
/// In both, Linux changes each owner word to `FUTEX_OWNER_DIED` in the native
/// exit, and Detcore only reads the words.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum OwnerDeathPath {
    /// The backend's exit callback comes after the native exit
    /// (`BackendCapabilities::runs_exit_robust_list`, ptrace). Wakes for a
    /// whole group's death wait for the owners' exit callbacks.
    Kernel,
    /// The backend reports a thread's exit before the native exit runs, and
    /// registers a pidfd for every host thread
    /// (`BackendCapabilities::requires_thread_directed_process_signals`, DBT).
    /// The scheduler then commits no turn until the kernel has ended a thread
    /// that exited by its own grant, or any thread of a group whose exit_group
    /// was granted (`Scheduler::exited_thread_barriers`). An exit_group's
    /// killed threads also hold their native exits until the group's walk is
    /// done (`ThreadState::wait_for_exit_group_robust_walk`), so that walk reads
    /// every word as the guest left it.
    Barrier,
}

/// How precise and polling futex modes answer a futex command, decided as
/// Linux's `do_futex` (kernel/futex/syscalls.c) decides it, before the futex
/// address is looked at.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum FutexCommand {
    /// Emulated: FUTEX_WAIT, FUTEX_WAIT_BITSET, FUTEX_WAKE, FUTEX_WAKE_BITSET,
    /// FUTEX_REQUEUE, FUTEX_CMP_REQUEUE, FUTEX_WAKE_OP, and the
    /// priority-inheritance lock commands FUTEX_LOCK_PI, FUTEX_LOCK_PI2,
    /// FUTEX_TRYLOCK_PI and FUTEX_UNLOCK_PI (`Detcore::handle_futex_lock_pi`,
    /// `Detcore::handle_futex_unlock_pi`).
    Served,
    /// `-ENOSYS`, exactly as Linux: FUTEX_CLOCK_REALTIME with any command but
    /// FUTEX_WAIT_BITSET, FUTEX_WAIT_REQUEUE_PI or FUTEX_LOCK_PI2; the removed
    /// FUTEX_FD; and any unknown command.
    NoSys,
    /// FUTEX_WAIT_REQUEUE_PI or FUTEX_CMP_REQUEUE_PI, the requeue-PI pair that
    /// moves a condition variable's waiters onto a PI mutex. Detcore does not
    /// emulate it; refused by name (`Detcore::refuse_futex_command`). glibc's
    /// condition variables have not issued it since glibc 2.25: they wait on
    /// their own words and then lock the mutex.
    RequeuePi(&'static str),
}

/// [`FutexCommand`] for a raw `futex_op`.
// AUTONOMOUS-BOT-IMPLEMENTED
pub(crate) fn classify_futex_command(futex_op: i32) -> FutexCommand {
    let cmd = futex_op & libc::FUTEX_CMD_MASK;
    if futex_op & libc::FUTEX_CLOCK_REALTIME != 0
        && !matches!(
            cmd,
            libc::FUTEX_WAIT_BITSET | libc::FUTEX_WAIT_REQUEUE_PI | libc::FUTEX_LOCK_PI2
        )
    {
        return FutexCommand::NoSys;
    }
    match cmd {
        libc::FUTEX_WAIT
        | libc::FUTEX_WAIT_BITSET
        | libc::FUTEX_WAKE
        | libc::FUTEX_WAKE_BITSET
        | libc::FUTEX_REQUEUE
        | libc::FUTEX_CMP_REQUEUE
        | libc::FUTEX_WAKE_OP
        // AUTONOMOUS-BOT-IMPLEMENTED
        | libc::FUTEX_LOCK_PI
        | libc::FUTEX_LOCK_PI2
        | libc::FUTEX_TRYLOCK_PI
        | libc::FUTEX_UNLOCK_PI => FutexCommand::Served,
        libc::FUTEX_WAIT_REQUEUE_PI => FutexCommand::RequeuePi("FUTEX_WAIT_REQUEUE_PI"),
        libc::FUTEX_CMP_REQUEUE_PI => FutexCommand::RequeuePi("FUTEX_CMP_REQUEUE_PI"),
        _ => FutexCommand::NoSys,
    }
}

/// Why `--debug-futex-mode polling` refuses FUTEX_REQUEUE, FUTEX_CMP_REQUEUE,
/// FUTEX_WAKE_OP and the priority-inheritance lock commands.
const POLLING_REFUSAL: &str = "--debug-futex-mode polling does not model futex waiter lists";

/// The name of a priority-inheritance lock command (FUTEX_LOCK_PI,
/// FUTEX_LOCK_PI2, FUTEX_TRYLOCK_PI, FUTEX_UNLOCK_PI), or `None` for any other.
fn pi_lock_command_name(command: i32) -> Option<&'static str> {
    match command {
        libc::FUTEX_LOCK_PI => Some("FUTEX_LOCK_PI"),
        libc::FUTEX_LOCK_PI2 => Some("FUTEX_LOCK_PI2"),
        libc::FUTEX_TRYLOCK_PI => Some("FUTEX_TRYLOCK_PI"),
        libc::FUTEX_UNLOCK_PI => Some("FUTEX_UNLOCK_PI"),
        _ => None,
    }
}

/// Whether the futex word at `address` lies in a file-backed shared mapping,
/// which a process outside Hermit can update concurrently. Detcore changes a
/// word with a separate read and write, which Linux's locked instruction does
/// not, so the commands that change their word refuse such a one.
fn futex_word_is_file_backed<T: RecordOrReplay, G: Guest<Detcore<T>>>(
    guest: &G,
    address: usize,
) -> bool {
    matches!(
        guest.thread_state().futex_id(address, false),
        FutexID::Shared {
            object: SharedMemoryObjectId::File { .. } | SharedMemoryObjectId::OpenFile { .. },
            ..
        }
    )
}

/// Write a futex word as a user-mode store does, which is what Linux's
/// `futex_cmpxchg_value_locked` and `futex_atomic_op_inuser` do: exactly four
/// bytes with the guest's own permissions, `-EFAULT` if the word cannot be
/// written.
fn write_futex_word<T: RecordOrReplay, G: Guest<Detcore<T>>>(
    guest: &mut G,
    address: usize,
    value: u32,
) -> Result<(), Error> {
    let word = AddrMut::<u32>::from_raw(address).ok_or(Errno::EFAULT)?;
    guest
        .memory()
        .write_value(word, &value)
        .map_err(|_| Error::Errno(Errno::EFAULT))
}

/// Why the priority-inheritance lock commands refuse a caller in a nested PID
/// namespace, whose futex words hold TIDs Detcore does not translate.
const NESTED_PID_NAMESPACE_REFUSAL: &str = "the caller is in a nested PID namespace, whose \
     priority-inheritance futex words hold TIDs Detcore does not translate";

/// Why a command that changes its futex word refuses a word in a file-backed
/// shared mapping (`futex_word_is_file_backed`).
const FILE_BACKED_WORD_REFUSAL: &str = "its word is in a file-backed shared mapping that a process \
     outside Hermit could update concurrently, and Detcore cannot apply the operation atomically";

/// The `val2` of FUTEX_REQUEUE, FUTEX_CMP_REQUEUE and FUTEX_WAKE_OP, which the
/// syscall passes in the timeout argument: `sys_futex` hands
/// `(unsigned long)utime` to `do_futex` as a `u32`, and the commands read it as
/// an `int`.
fn futex_val2(call: &syscalls::Futex) -> u32 {
    call.timeout().map_or(0, Addr::as_raw) as u32
}

/// The raw `uaddr2` argument; NULL is address 0, as Linux keys it.
fn futex_uaddr2(call: &syscalls::Futex) -> usize {
    call.uaddr2().map_or(0, AddrMut::as_raw)
}

/// The raw `uaddr` of a futex call; NULL is a valid private key for the
/// commands that only key their words.
fn futex_uaddr(call: &syscalls::Futex) -> usize {
    call.uaddr().map_or(0, AddrMut::as_raw)
}

/// How a command acquires a futex key: Linux's `enum futex_access`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum KeyAccess {
    /// `FUTEX_READ`: the word is only compared or woken.
    Read,
    /// `FUTEX_WRITE`: the word is changed (WAKE_OP's second word).
    Write,
}

/// The highest address `access_ok` accepts for a futex word on this host,
/// `USER_PTR_MAX` (arch/x86/include/asm/uaccess_64.h). It depends on the
/// paging mode the kernel booted with, so it is measured once from the host
/// kernel, which is also the guest's kernel: a private FUTEX_WAKE with count 0
/// keys the word without touching it and fails with EFAULT exactly when
/// `access_ok` refuses it.
pub(crate) fn user_ptr_max() -> usize {
    static MAX: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
    *MAX.get_or_init(|| {
        let accepted = |address: usize| {
            // SAFETY: a private FUTEX_WAKE with count 0 never accesses `address`.
            let ret = unsafe {
                libc::syscall(
                    libc::SYS_futex,
                    address,
                    libc::FUTEX_WAKE | libc::FUTEX_PRIVATE_FLAG,
                    0,
                    0,
                    0,
                    0,
                )
            };
            ret >= 0
        };
        // Binary search over 4-aligned addresses: 0 is accepted, and an address
        // past the largest user address space never is. The bound stays below
        // any tag bits (arm64's top byte, x86's bits 57 to 62), so the search
        // stays monotone even if Hermit itself ran with tagging enabled.
        let bad_start = if cfg!(target_arch = "aarch64") {
            1usize << 55
        } else {
            1usize << 57
        };
        let (mut ok, mut bad) = (0usize, bad_start);
        while bad - ok > 4 {
            let mid = (ok + (bad - ok) / 2) & !3;
            if accepted(mid) { ok = mid } else { bad = mid }
        }
        ok
    })
}

/// The futex key of a word that a command keys, as Linux's `get_futex_key`
/// (kernel/futex/core.c) admits it, without reading the word:
/// - `-EINVAL` if it is not 4-aligned;
/// - `-EFAULT` if `access_ok` refuses it (`user_ptr_max`);
/// - a private key needs nothing more, so NULL is a valid one;
/// - a shared key needs its backing page, acquired for reading or writing.
///   Which pages the kernel can acquire (a copy-on-write page made read-only, a
///   page past the end of a truncated file, a read-only anonymous page) is not
///   visible in `/proc` metadata, so the kernel is asked with an effect-free
///   probe on the guest's own address (`probe_shared_futex_key`).
async fn futex_key<G: Guest<Detcore<T>>, T: RecordOrReplay>(
    guest: &mut G,
    address: usize,
    private: bool,
    access: KeyAccess,
) -> Result<FutexID, Error> {
    if !address.is_multiple_of(std::mem::size_of::<u32>()) {
        return Err(Error::Errno(Errno::EINVAL));
    }
    if address > user_ptr_max() {
        return Err(Error::Errno(Errno::EFAULT));
    }
    if !private {
        probe_shared_futex_key(guest, address, access).await?;
    }
    Ok(guest.thread_state().futex_id(address, private))
}

/// Whether the kernel admits `address` as a shared futex key with `access`,
/// asked with a futex call injected into the guest that runs `get_futex_key`
/// and has no other effect, even on a waiter outside Hermit:
/// - a READ key: a non-private FUTEX_REQUEUE from the word to itself with both
///   counts 0. `futex_requeue` acquires both keys for reading, and its loop
///   then stops before the first waiter (`task_count - nr_wake >= nr_requeue`).
///   A FUTEX_WAKE with count 0 would not do: it still wakes one waiter;
/// - a WRITE key: a non-private FUTEX_WAKE_OP from the word to itself with an
///   unknown operation. `futex_wake_op` acquires the first key for reading and
///   the second for writing, then `futex_atomic_op_inuser` returns -ENOSYS for
///   the unknown operation before it touches the word or wakes anyone.
///
/// Linux's refusal (-EFAULT, or -EINVAL) is returned as is.
async fn probe_shared_futex_key<G: Guest<Detcore<T>>, T: RecordOrReplay>(
    guest: &mut G,
    address: usize,
    access: KeyAccess,
) -> Result<(), Error> {
    let probe = shared_futex_key_probe(address, access);
    match run_shared_futex_key_probe(guest, probe, access, |guest, probe| guest.inject(probe)).await
    {
        SharedKeyProbe::Admitted => Ok(()),
        SharedKeyProbe::Refused(errno) => Err(Error::Errno(errno)),
        SharedKeyProbe::Interrupted(errno) => {
            refuse_interrupted_shared_key_probe(guest, address, errno).await
        }
    }
}

/// The effect-free futex call that asks the kernel whether `address` is a
/// shared key with `access` (see `probe_shared_futex_key`).
fn shared_futex_key_probe(address: usize, access: KeyAccess) -> syscalls::Futex {
    let word = AddrMut::<libc::c_int>::from_raw(address);
    match access {
        KeyAccess::Read => syscalls::Futex::new()
            .with_uaddr(word)
            .with_futex_op(libc::FUTEX_REQUEUE)
            .with_val(0)
            .with_uaddr2(word),
        KeyAccess::Write => syscalls::Futex::new()
            .with_uaddr(word)
            .with_futex_op(libc::FUTEX_WAKE_OP)
            .with_val(0)
            .with_uaddr2(word)
            .with_val3((7 << 28) | (1 << 12)),
    }
}

/// The pending answer to one injected shared-key probe.
type KeyProbeAnswer<'a> =
    std::pin::Pin<Box<dyn std::future::Future<Output = Result<i64, Errno>> + Send + 'a>>;

/// What one injected shared-key probe answered.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum SharedKeyProbe {
    /// The kernel admitted the key: 0, or ENOSYS for a WRITE key (the unknown
    /// WAKE_OP operation is rejected only after both keys are acquired).
    Admitted,
    /// The kernel refused the key with this errno, which is the guest's.
    Refused(Errno),
    /// A signal stopped the probe's instruction before it ran (Reverie's
    /// `Guest::inject` returns ERESTARTSYS; EINTR is never a key answer either,
    /// since neither probe sleeps). The kernel answered nothing.
    Interrupted(Errno),
}

/// Inject a shared-key `probe` once with `inject` and classify the answer.
///
/// The probe is never injected again: Reverie holds the signal that stopped
/// it in a single slot, and a second interrupted injection would replace that
/// signal, losing one the kernel already dequeued (Codex re-check #4 of
/// https://github.com/rrnewton/hermit/pull/4020). An interruption is returned
/// as such, never as an admission or as the guest's errno.
async fn run_shared_futex_key_probe<C>(
    context: &mut C,
    probe: syscalls::Futex,
    access: KeyAccess,
    inject: for<'a> fn(&'a mut C, syscalls::Futex) -> KeyProbeAnswer<'a>,
) -> SharedKeyProbe {
    match inject(context, probe).await {
        Ok(_) => SharedKeyProbe::Admitted,
        Err(errno @ (Errno::ERESTARTSYS | Errno::EINTR)) => SharedKeyProbe::Interrupted(errno),
        Err(Errno::ENOSYS) if access == KeyAccess::Write => SharedKeyProbe::Admitted,
        Err(errno) => SharedKeyProbe::Refused(errno),
    }
}

/// Stop the run by name because a signal interrupted the shared-key probe for
/// the futex word at `address`.
///
/// The original call has no answer to return: the interruption token is not a
/// Linux result for it, retrying could lose the held signal
/// (`run_shared_futex_key_probe`), and admitting the key unchecked could be a
/// silent wrong answer. The run ends with the policy-refusal status whatever
/// the unsupported-operation policy, since `--allow-unsupported-syscalls` has
/// no errno to offer here either. A signal must arrive at exactly that
/// instruction, which is rare.
async fn refuse_interrupted_shared_key_probe<G: Guest<Detcore<T>>, T: RecordOrReplay>(
    guest: &mut G,
    address: usize,
    errno: Errno,
) -> ! {
    {
        use std::io::Write;
        let _ = writeln!(
            crate::util::RetryingStderr,
            "hermit: a signal interrupted Detcore's shared futex key check for word {:#x} in thread {} ({}); \
             refusing the run rather than retrying it, which could lose that signal \
             (https://github.com/rrnewton/hermit/pull/4020)",
            address,
            guest.thread_state().dettid,
            errno,
        );
    }
    crate::tool_global::unrecoverable_shutdown(guest, detcore_model::HERMIT_POLICY_REFUSAL_EXIT)
        .await
}

/// A futex word's value as a user-mode access reads it, which is what Linux's
/// `futex_get_value_locked`/`get_user` and `futex_atomic_op_inuser` do:
/// `-EFAULT` if the word cannot be read.
///
/// The word is read as exactly four bytes with the guest's own permissions. On
/// x86 a writable page is also readable from user mode, but that read refuses a
/// mapping without `PROT_READ`, so for a writable one the 8-byte-aligned word
/// containing it is read instead. That cannot cross into the next page, unlike a
/// debugger read at the word's own address. A debugger read alone would also
/// ignore `PROT_NONE`.
fn read_futex_word<G: Guest<Detcore<T>>, T: RecordOrReplay>(
    guest: &mut G,
    address: usize,
) -> Result<i32, Error> {
    let word = Addr::<u8>::from_raw(address).ok_or(Errno::EFAULT)?;
    let mut bytes = [0u8; 4];
    if guest
        .memory()
        .read_exact_with_user_access(word, &mut bytes)
        .is_ok()
    {
        return Ok(i32::from_ne_bytes(bytes));
    }
    // Only a backend that runs the guest as real host threads has a host
    // `/proc/<pid>/maps` describing the guest; elsewhere (KVM's guest pid is
    // virtual) the user-access read above is the backend's whole answer.
    if !guest.config().backend.host_task_reads_reach_guest_threads
        || !mapping_is_writable(guest.pid().as_raw(), address)
    {
        return Err(Error::Errno(Errno::EFAULT));
    }
    let aligned = address & !(std::mem::size_of::<u64>() - 1);
    let pair: u64 = guest
        .memory()
        .read_value(Addr::<u64>::from_raw(aligned).ok_or(Errno::EFAULT)?)
        .map_err(|_| Error::Errno(Errno::EFAULT))?;
    let offset = address - aligned;
    let pair = pair.to_ne_bytes();
    bytes.copy_from_slice(&pair[offset..offset + 4]);
    Ok(i32::from_ne_bytes(bytes))
}

/// Write only Linux's sched_param word, never an extended target-libc wrapper.
fn write_sched_getparam<M: MemoryAccess>(
    memory: &mut M,
    param: AddrMut<'_, syscalls::linux_abi::SchedParam>,
) -> Result<(), Errno> {
    memory.write_value(
        param,
        &syscalls::linux_abi::SchedParam { sched_priority: 0 },
    )
}

/// Whether the guest mapping containing `address` is writable, from
/// `/proc/<pid>/maps`. False if no mapping contains it or the file cannot be
/// read.
fn mapping_is_writable(pid: i32, address: usize) -> bool {
    mapping_permissions(pid, address).is_some_and(|perms| perms[1] == b'w')
}

/// The `rwxp` permissions of the guest mapping containing `address`, from
/// `/proc/<pid>/maps`, or `None` if no mapping contains it or the file cannot be
/// read.
fn mapping_permissions(pid: i32, address: usize) -> Option<[u8; 4]> {
    let maps = std::fs::read_to_string(format!("/proc/{pid}/maps")).ok()?;
    maps.lines().find_map(|line| {
        let mut fields = line.split_whitespace();
        let (Some(range), Some(perms)) = (fields.next(), fields.next()) else {
            return None;
        };
        let (start, end) = range.split_once('-')?;
        let (Ok(start), Ok(end)) = (
            usize::from_str_radix(start, 16),
            usize::from_str_radix(end, 16),
        ) else {
            return None;
        };
        if !(start..end).contains(&address) {
            return None;
        }
        perms.as_bytes().get(..4)?.try_into().ok()
    })
}

/// A `struct timespec` copied from the guest as Linux's `get_timespec64`
/// (`copy_from_user`) copies it: every byte must lie in a mapping user mode can
/// read, which on x86 includes a write-only one, or the copy is EFAULT, with no
/// partial result. On a backend whose guest is real host threads, the guest's
/// host `/proc/<pid>/maps` decides; elsewhere the backend's user-access read. The bytes are then read through the tracer, which is only
/// safe because every page they span was checked first: the tracer's own read
/// would force its way through a PROT_NONE page.
fn read_user_timespec<G: Guest<Detcore<T>>, T: RecordOrReplay>(
    guest: &mut G,
    address: usize,
) -> Result<Timespec, Error> {
    let size = std::mem::size_of::<Timespec>();
    let last = address.checked_add(size - 1).ok_or(Errno::EFAULT)?;
    if last > user_ptr_max() {
        return Err(Error::Errno(Errno::EFAULT));
    }
    if !guest.config().backend.host_task_reads_reach_guest_threads {
        // No host `/proc` describes this guest (KVM's guest pid is virtual), so
        // the backend's own user-access read decides, all or nothing.
        let mut bytes = [0u8; std::mem::size_of::<Timespec>()];
        guest
            .memory()
            .read_exact_with_user_access(
                Addr::<u8>::from_raw(address).ok_or(Errno::EFAULT)?,
                &mut bytes,
            )
            .map_err(|_| Error::Errno(Errno::EFAULT))?;
        let field = |at: usize| -> i64 {
            let mut raw = [0u8; 8];
            raw.copy_from_slice(&bytes[at..at + 8]);
            i64::from_ne_bytes(raw)
        };
        return Ok(Timespec {
            tv_sec: field(0) as libc::time_t,
            tv_nsec: field(8) as libc::c_long,
        });
    }
    // 4096 divides every page size, so probing each 4 KiB step checks every page.
    let page = 4096;
    let pid = guest.pid().as_raw();
    let mut cursor = address & !(page - 1);
    while cursor <= last {
        let probe = cursor.max(address);
        let readable = mapping_permissions(pid, probe)
            .is_some_and(|perms| perms[0] == b'r' || perms[1] == b'w');
        if !readable {
            return Err(Error::Errno(Errno::EFAULT));
        }
        cursor += page;
    }
    // Read the bytes as aligned 8-byte words, which the tracer reads one at a
    // time even from a write-only page; a larger read goes through
    // `process_vm_readv`, which needs the page to be readable.
    let start = address & !7;
    let mut bytes = Vec::with_capacity(last + 1 - start);
    let mut word = start;
    while word <= last {
        let value: u64 = guest
            .memory()
            .read_value(Addr::<u64>::from_raw(word).ok_or(Errno::EFAULT)?)
            .map_err(|_| Error::Errno(Errno::EFAULT))?;
        bytes.extend_from_slice(&value.to_ne_bytes());
        word += 8;
    }
    let field = |at: usize| -> i64 {
        let mut raw = [0u8; 8];
        raw.copy_from_slice(&bytes[address - start + at..address - start + at + 8]);
        i64::from_ne_bytes(raw)
    };
    Ok(Timespec {
        tv_sec: field(0) as libc::time_t,
        tv_nsec: field(8) as libc::c_long,
    })
}

// FUTEX_WAKE_OP operations and comparisons (include/uapi/linux/futex.h).
const FUTEX_OP_SET: u32 = 0;
const FUTEX_OP_ADD: u32 = 1;
const FUTEX_OP_OR: u32 = 2;
const FUTEX_OP_ANDN: u32 = 3;
const FUTEX_OP_XOR: u32 = 4;
const FUTEX_OP_OPARG_SHIFT: u32 = 8;
const FUTEX_OP_CMP_EQ: u32 = 0;
const FUTEX_OP_CMP_NE: u32 = 1;
const FUTEX_OP_CMP_LT: u32 = 2;
const FUTEX_OP_CMP_GE: u32 = 3;
const FUTEX_OP_CMP_LE: u32 = 4;
const FUTEX_OP_CMP_GT: u32 = 5;

/// FUTEX_WAKE_OP's encoded operation, decoded as Linux's
/// `futex_atomic_op_inuser` (kernel/futex/waitwake.c) decodes it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct FutexWakeOp {
    op: u32,
    cmp: u32,
    oparg: i32,
    cmparg: i32,
}

impl FutexWakeOp {
    pub(crate) fn decode(encoded: u32) -> Self {
        let sign_extend_12 = |v: u32| ((v << 20) as i32) >> 20;
        let op = (encoded & 0x7000_0000) >> 28;
        let cmp = (encoded & 0x0f00_0000) >> 24;
        let mut oparg = sign_extend_12((encoded & 0x00ff_f000) >> 12);
        let cmparg = sign_extend_12(encoded & 0x0000_0fff);
        if encoded & (FUTEX_OP_OPARG_SHIFT << 28) != 0 {
            // Linux masks an out-of-range shift (and logs "fix this program").
            if !(0..=31).contains(&oparg) {
                oparg &= 31;
            }
            oparg = 1i32.wrapping_shl(oparg as u32);
        }
        FutexWakeOp {
            op,
            cmp,
            oparg,
            cmparg,
        }
    }

    /// Whether the operation is one x86's `arch_futex_atomic_op_inuser` knows;
    /// it returns `-ENOSYS` for any other before touching the word.
    pub(crate) fn has_known_operation(&self) -> bool {
        self.apply(0).is_some()
    }

    /// The new value of the word, from its old value.
    pub(crate) fn apply(&self, old: i32) -> Option<i32> {
        Some(match self.op {
            FUTEX_OP_SET => self.oparg,
            FUTEX_OP_ADD => old.wrapping_add(self.oparg),
            FUTEX_OP_OR => old | self.oparg,
            FUTEX_OP_ANDN => old & !self.oparg,
            FUTEX_OP_XOR => old ^ self.oparg,
            _ => return None,
        })
    }

    /// Whether to wake on `uaddr2`, from the word's old value; `None` (`-ENOSYS`)
    /// for an unknown comparison.
    pub(crate) fn compare(&self, old: i32) -> Option<bool> {
        Some(match self.cmp {
            FUTEX_OP_CMP_EQ => old == self.cmparg,
            FUTEX_OP_CMP_NE => old != self.cmparg,
            FUTEX_OP_CMP_LT => old < self.cmparg,
            FUTEX_OP_CMP_GE => old >= self.cmparg,
            FUTEX_OP_CMP_LE => old <= self.cmparg,
            FUTEX_OP_CMP_GT => old > self.cmparg,
            _ => return None,
        })
    }
}

#[cfg(test)]
mod tests {

    struct SchedParamMemory {
        bytes: [u8; 16],
        writable_end: usize,
        requested: Vec<usize>,
    }
    impl MemoryAccess for SchedParamMemory {
        fn read_vectored(
            &self,
            _: &[std::io::IoSlice<'_>],
            _: &mut [std::io::IoSliceMut<'_>],
        ) -> Result<usize, Errno> {
            panic!("sched_getparam must not read guest memory")
        }
        fn write_vectored(
            &mut self,
            _: &[std::io::IoSlice<'_>],
            _: &mut [std::io::IoSliceMut<'_>],
        ) -> Result<usize, Errno> {
            panic!("the offset-based mock must use write directly")
        }
        fn write(&mut self, address: AddrMut<u8>, source: &[u8]) -> Result<usize, Errno> {
            // The address is an offset into this mock, not a live pointer. Do
            // not construct a slice from it through the default write method.
            let start = address.as_raw();
            let want = source.len();
            self.requested.push(want);
            if start
                .checked_add(want)
                .is_none_or(|end| end > self.writable_end)
            {
                return Err(Errno::EFAULT);
            }
            self.bytes[start..start + want].copy_from_slice(source);
            Ok(want)
        }
    }

    #[test]
    fn sched_getparam_writes_only_kernel_priority_before_guard() {
        let mut memory = SchedParamMemory {
            bytes: [0xA5; 16],
            writable_end: 5,
            requested: Vec::new(),
        };
        let param = AddrMut::<syscalls::linux_abi::SchedParam>::from_raw(1).unwrap();
        assert_eq!(write_sched_getparam(&mut memory, param), Ok(()));
        assert_eq!(memory.requested, vec![4]);
        assert_eq!(&memory.bytes[1..5], &0i32.to_ne_bytes());
        assert_eq!(memory.bytes[0], 0xA5);
        assert_eq!(&memory.bytes[5..], &[0xA5; 11]);
    }

    #[test]
    fn sched_getparam_short_writable_kernel_word_remains_efault() {
        let mut memory = SchedParamMemory {
            bytes: [0xA5; 16],
            writable_end: 4,
            requested: Vec::new(),
        };
        let param = AddrMut::<syscalls::linux_abi::SchedParam>::from_raw(1).unwrap();
        assert_eq!(write_sched_getparam(&mut memory, param), Err(Errno::EFAULT));
        assert_eq!(memory.requested, vec![4]);
        assert_eq!(memory.bytes, [0xA5; 16]);
    }

    /// A copy the record marks as discarded at send is left out even when the
    /// wake's answer names its signal (`committed`), as for a drain batch's
    /// copy that was flushed and sent again, discarded (R4-1 of the R2b-1
    /// design re-checks, https://github.com/rrnewton/hermit/issues/4273; arm
    /// A9). A kept copy in either queue stays.
    #[test]
    fn a_discarded_copy_is_left_out_even_when_committed() {
        let chld = kernel_sigset_bit(libc::SIGCHLD);
        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
        let state = KernelSignalState {
            pending: chld | usr1,
            thread_pending: chld,
            shared_pending: usr1,
            ..Default::default()
        };
        assert_eq!(with_kept_copies(&state, chld, 0, chld | usr1, chld), usr1);
        assert_eq!(with_kept_copies(&state, 0, usr1, chld | usr1, usr1), chld);
        assert_eq!(with_kept_copies(&state, 0, 0, chld | usr1, 0), chld | usr1);
    }
    use std::io::Read;
    use std::io::Seek;
    use std::os::fd::AsRawFd;

    use reverie::GlobalRPC;
    use reverie::GlobalTool;
    use reverie::Tid;
    use reverie::Tool;

    use super::*;

    /// The Kernel path is ptrace's, and the Barrier path is DBT's alone: a
    /// backend gets the Barrier path only by setting a flag whose other
    /// properties it must then have (`owner_death_path`).
    #[test]
    fn owner_death_path_is_tied_to_the_backends_that_have_its_properties() {
        let path = |backend: reverie::BackendCapabilities| {
            let mut cfg = Config::default().with_backend(|capabilities| *capabilities = backend);
            cfg.sequentialize_threads = true;
            cfg.debug_futex_mode = BlockingMode::Precise;
            owner_death_path(&cfg)
        };
        assert_eq!(
            path(reverie::BackendCapabilities::PTRACE),
            Some(OwnerDeathPath::Kernel)
        );
        assert_eq!(
            path(reverie::BackendCapabilities::DBT),
            Some(OwnerDeathPath::Barrier)
        );
        for backend in [
            reverie::BackendCapabilities::KVM,
            reverie::BackendCapabilities::SABRE,
            reverie::BackendCapabilities::LITEINST_IN_GUEST,
        ] {
            assert_eq!(path(backend), None, "{backend:?}");
        }
    }

    /// Each configuration takes its own `sched_yield` route; only chaos with
    /// the timer on and delivered, no schedule replay, and a heuristic other
    /// than `Random` takes the yield epoch, and an ordinary run still ends its
    /// timeslice (https://github.com/rrnewton/hermit/issues/4068,
    /// https://github.com/rrnewton/hermit/issues/4150).
    #[test]
    fn each_configuration_takes_its_sched_yield_route() {
        let path = || Some(std::path::PathBuf::from("record.json"));
        let cases = [
            (Config::default(), SchedYieldRoute::EndTimeslice),
            // The ordinary ptrace run: timers delivered, no chaos.
            (
                Config {
                    ..Config::default()
                }
                .with_backend(|backend| {
                    backend.delivers_preemption_timer_events = true;
                    backend.runs_guest_code_between_injections = false;
                }),
                SchedYieldRoute::EndTimeslice,
            ),
            (
                Config {
                    chaos: true,
                    replay_schedule_from: path(),
                    ..Config::default()
                }
                .with_backend(|backend| {
                    backend.delivers_preemption_timer_events = true;
                    backend.runs_guest_code_between_injections = false;
                }),
                SchedYieldRoute::WeakYield,
            ),
            (
                Config {
                    chaos: true,
                    ..Config::default()
                }
                .with_backend(|backend| {
                    backend.delivers_preemption_timer_events = true;
                    backend.runs_guest_code_between_injections = false;
                }),
                SchedYieldRoute::ChaosYieldEpoch,
            ),
            (
                Config {
                    chaos: true,
                    sched_heuristic: SchedHeuristic::Random,
                    ..Config::default()
                }
                .with_backend(|backend| {
                    backend.delivers_preemption_timer_events = true;
                    backend.runs_guest_code_between_injections = false;
                }),
                SchedYieldRoute::WeakYield,
            ),
            (
                Config {
                    chaos: true,
                    sched_heuristic: SchedHeuristic::StickyRandom,
                    ..Config::default()
                }
                .with_backend(|backend| {
                    backend.delivers_preemption_timer_events = true;
                    backend.runs_guest_code_between_injections = false;
                }),
                SchedYieldRoute::ChaosYieldEpoch,
            ),
            (
                Config {
                    chaos: true,
                    sched_heuristic: SchedHeuristic::ConnectBind,
                    ..Config::default()
                }
                .with_backend(|backend| {
                    backend.delivers_preemption_timer_events = true;
                    backend.runs_guest_code_between_injections = false;
                }),
                SchedYieldRoute::ChaosYieldEpoch,
            ),
            (
                Config {
                    chaos: true,
                    max_timeslice: None,
                    sched_heuristic: SchedHeuristic::Random,
                    ..Config::default()
                },
                SchedYieldRoute::ChaosReprioritize,
            ),
            // A backend that delivers no preemption timer events.
            (
                Config {
                    chaos: true,
                    ..Config::default()
                }
                .with_backend(|backend| backend.delivers_preemption_timer_events = false),
                SchedYieldRoute::WeakYield,
            ),
            (
                Config {
                    chaos: true,
                    max_timeslice: None,
                    ..Config::default()
                },
                SchedYieldRoute::ChaosReprioritize,
            ),
            (
                Config {
                    chaos: true,
                    replay_preemptions_from: path(),
                    ..Config::default()
                }
                .with_backend(|backend| {
                    backend.delivers_preemption_timer_events = true;
                    backend.runs_guest_code_between_injections = false;
                }),
                SchedYieldRoute::ChaosYieldEpoch,
            ),
            (
                Config {
                    chaos: true,
                    replay_schedule_from: path(),
                    ..Config::default()
                },
                SchedYieldRoute::WeakYield,
            ),
            (
                Config {
                    replay_schedule_from: path(),
                    ..Config::default()
                },
                SchedYieldRoute::WeakYield,
            ),
            (
                Config {
                    replay_preemptions_from: path(),
                    ..Config::default()
                },
                SchedYieldRoute::ReplayStrongYield,
            ),
        ];
        for (cfg, route) in cases {
            assert_eq!(
                sched_yield_route(&cfg),
                route,
                "chaos={} timer delivered={} heuristic={:?} max_timeslice={:?} preemptions={:?} schedule={:?}",
                cfg.chaos,
                cfg.backend.delivers_preemption_timer_events,
                cfg.sched_heuristic,
                cfg.max_timeslice,
                cfg.replay_preemptions_from,
                cfg.replay_schedule_from
            );
        }
    }

    /// A thread whose reported pid is not its thread group, as Reverie
    /// reports for a process that a raw `clone` without `CLONE_THREAD` made,
    /// still has a readable signal state and is not taken to be gone
    /// (https://github.com/rrnewton/hermit/issues/3982). The test's own thread
    /// stands in for it, with this process's parent as the wrong pid.
    #[test]
    fn a_thread_reported_under_another_pid_is_read_and_alive() {
        let tid = Pid::from_raw(unsafe { libc::syscall(libc::SYS_gettid) } as i32);
        let wrong = Pid::from_raw(unsafe { libc::getppid() });
        assert_ne!(wrong, tid);
        assert!(read_kernel_signal_state(wrong, tid).is_err());
        assert!(read_thread_signal_state(wrong, tid).is_ok());
        assert!(!thread_is_gone(wrong, tid));
        assert!(read_thread_wait_signal_state(wrong, tid).is_ok());
    }

    /// Host `/proc` signal state reads are forbidden exactly where guest
    /// thread IDs do not name host tasks: KVM, and no other backend today.
    #[test]
    fn host_signal_state_reads_are_refused_only_where_guest_tids_are_not_host_tasks() {
        assert!(refuses_host_signal_state_reads(&BackendCapabilities::KVM));
        for backend in [
            BackendCapabilities::PTRACE,
            BackendCapabilities::E9PATCH,
            BackendCapabilities::SABRE,
            BackendCapabilities::DBT,
            BackendCapabilities::LITEINST_IN_GUEST,
        ] {
            assert!(!refuses_host_signal_state_reads(&backend));
        }
    }

    /// Once the refusal is latched for a backend whose guest thread IDs are
    /// not host tasks, a signal state read never reaches `/proc`: the test's
    /// own live thread, whose state is readable before, is refused after.
    #[test]
    fn a_latched_refusal_never_reads_a_host_task_signal_state() {
        let pid = Pid::from_raw(unsafe { libc::getpid() });
        let tid = Pid::from_raw(unsafe { libc::syscall(libc::SYS_gettid) } as i32);
        refuse_host_signal_state_reads(&BackendCapabilities::PTRACE);
        assert!(!host_signal_state_reads_refused());
        assert!(read_kernel_signal_state(pid, tid).is_ok());
        refuse_host_signal_state_reads(&BackendCapabilities::KVM);
        assert!(host_signal_state_reads_refused());
        assert_eq!(read_kernel_signal_state(pid, tid), Err(Errno::ENOSYS));
        assert_eq!(read_thread_signal_state(pid, tid), Err(Errno::ENOSYS));
    }

    /// A kept status file is read afresh each time: a signal blocked after
    /// the first read shows in the second, which reuses the kept file, and the
    /// thread's exit hook drops it (`forget_thread_status`).
    #[test]
    fn a_kept_status_file_reads_the_current_state_until_its_thread_is_forgotten() {
        std::thread::spawn(|| {
            status_files::enable();
            let pid = Pid::from_raw(unsafe { libc::getpid() });
            let tid = Pid::from_raw(unsafe { libc::syscall(libc::SYS_gettid) } as i32);
            let usr2 = crate::scheduler::kernel_signal_bit(libc::SIGUSR2);
            let before = read_kernel_signal_state(pid, tid).unwrap();
            assert_eq!(before.blocked & usr2, 0);
            assert!(status_files::keeps(pid, tid));
            // SAFETY: changes only this spawned thread's own mask.
            unsafe {
                let mut set: libc::sigset_t = std::mem::zeroed();
                libc::sigemptyset(&mut set);
                libc::sigaddset(&mut set, libc::SIGUSR2);
                assert_eq!(
                    libc::pthread_sigmask(libc::SIG_BLOCK, &set, std::ptr::null_mut()),
                    0
                );
            }
            let after = read_kernel_signal_state(pid, tid).unwrap();
            assert_eq!(after.blocked & usr2, usr2);
            assert!(status_files::keeps(pid, tid));
            forget_thread_status(tid);
            assert!(!status_files::keeps(pid, tid));
        })
        .join()
        .unwrap();
    }

    /// Until keeping is enabled, which only Hermit's own process does, a read
    /// keeps no file: no descriptor of this process names the thread's status
    /// file afterwards. Detcore linked into a guest is in this state, so its
    /// reads leave nothing in the guest's descriptor table.
    #[test]
    #[allow(clippy::disallowed_methods)] // a host unit test lists its own descriptors
    fn without_keeping_a_read_leaves_no_descriptor_open() {
        std::thread::spawn(|| {
            let pid = Pid::from_raw(unsafe { libc::getpid() });
            let tid = Pid::from_raw(unsafe { libc::syscall(libc::SYS_gettid) } as i32);
            assert!(read_kernel_signal_state(pid, tid).is_ok());
            assert!(read_kernel_signal_state(pid, tid).is_ok());
            assert!(status_files::kept_file(pid, tid).is_none());
            let status = format!("/proc/{}/task/{}/status", pid.as_raw(), tid.as_raw());
            for entry in std::fs::read_dir("/proc/self/fd").unwrap() {
                let target = std::fs::read_link(entry.unwrap().path()).unwrap_or_default();
                assert_ne!(target.to_str(), Some(status.as_str()));
            }
            forget_thread_status(tid);
        })
        .join()
        .unwrap();
    }

    /// A kept status file stays bound to the thread it was opened for: once
    /// that thread has exited, the kept file is unreadable (`ESRCH`), so a
    /// read never takes a later thread's state from it. The read then drops
    /// the file and reads the path, as it did before files were kept: `ESRCH`
    /// while the TID is free, or the state of a thread that reused it (other
    /// tests in this process start threads concurrently).
    #[test]
    fn a_kept_status_file_of_an_exited_thread_is_unreadable_and_dropped() {
        status_files::enable();
        let pid = Pid::from_raw(unsafe { libc::getpid() });
        let (tid, kept) = std::thread::spawn(move || {
            status_files::enable();
            let tid = Pid::from_raw(unsafe { libc::syscall(libc::SYS_gettid) } as i32);
            assert!(read_kernel_signal_state(pid, tid).is_ok());
            let kept = status_files::kept_file(pid, tid).expect("the read keeps its file");
            (tid, kept)
        })
        .join()
        .unwrap();
        // join() returns before the kernel has finished tearing the thread
        // down; until then the kept file still reads it (as its path would).
        // Every read names that thread, and the file becomes unreadable.
        let deadline = std::time::Instant::now() + Duration::from_secs(5);
        let error = loop {
            match status_files::read_kept(&kept) {
                Ok(text) => {
                    let own = format!("\nPid:\t{}\n", tid.as_raw());
                    assert!(text.contains(&own), "{text}");
                    assert!(std::time::Instant::now() < deadline, "{text}");
                    std::thread::sleep(Duration::from_millis(1));
                }
                Err(error) => break error,
            }
        };
        assert_eq!(error.raw_os_error(), Some(libc::ESRCH));
        match read_kernel_signal_state(pid, tid) {
            Err(errno) => {
                assert_eq!(errno, Errno::ESRCH);
                assert!(!status_files::keeps(pid, tid));
            }
            // A thread of another test took the TID: the read is the path's.
            Ok(_) => {
                // The kept file, if any, is the reopened one (the cache may be
                // full of other tests' threads, which never run the exit hook).
                if let Some(now) = status_files::kept_file(pid, tid) {
                    assert!(!Arc::ptr_eq(&now, &kept));
                }
            }
        }
        assert!(status_files::kept() <= status_files::CAPACITY);
    }
    use crate::config::Config;
    use crate::tool_global::GlobalRequest;
    use crate::tool_global::GlobalState;
    use crate::types::MmId;

    /// A new process whose exit signal is not SIGCHLD makes its creator hold
    /// that signal; a thread, a `CLONE_PARENT` child, a SIGCHLD child, and an
    /// out-of-range signal add nothing
    /// (https://github.com/rrnewton/hermit/issues/3146).
    #[test]
    fn a_child_exit_signal_other_than_sigchld_is_host_timed_for_its_creator() {
        let usr1 = 1_u64 << (libc::SIGUSR1 - 1);
        let none = CloneFlags::empty();
        assert_eq!(clone_host_timed_signals(none, libc::SIGUSR1), usr1);
        assert_eq!(
            clone_host_timed_signals(CloneFlags::CLONE_VFORK, libc::SIGUSR1),
            usr1
        );
        assert_eq!(clone_host_timed_signals(none, libc::SIGCHLD), 0);
        assert_eq!(clone_host_timed_signals(none, 0), 0);
        assert_eq!(clone_host_timed_signals(none, 65), 0);
        let thread = CloneFlags::CLONE_THREAD | CloneFlags::CLONE_SIGHAND | CloneFlags::CLONE_VM;
        assert_eq!(clone_host_timed_signals(thread, libc::SIGUSR1), 0);
        assert_eq!(
            clone_host_timed_signals(CloneFlags::CLONE_PARENT, libc::SIGUSR1),
            0
        );
    }

    struct FailedExecStack;
    struct FailedExecStackGuard;

    impl Drop for FailedExecStackGuard {
        fn drop(&mut self) {}
    }

    impl reverie::Stack for FailedExecStack {
        type StackGuard = FailedExecStackGuard;

        fn size(&self) -> usize {
            panic!("failed exec must not use the guest stack")
        }
        fn capacity(&self) -> usize {
            panic!("failed exec must not use the guest stack")
        }
        fn push<'stack, T>(&mut self, _: T) -> Addr<'stack, T> {
            panic!("failed exec must not use the guest stack")
        }
        fn reserve<'stack, T>(&mut self) -> AddrMut<'stack, T> {
            panic!("failed exec must not use the guest stack")
        }
        fn commit(self) -> Result<Self::StackGuard, Errno> {
            panic!("failed exec must not use the guest stack")
        }
    }

    // Inject only the backend's errno and, when the backend refuses the exec
    // as unsupported, its typed refusal. Preparation, rollback, cancellation,
    // unsupported reporting and the configured refusal policy are real code.
    struct FailedExecGuest<'a> {
        config: &'a Config,
        global: &'a GlobalState,
        thread: crate::ThreadState<()>,
        sender: Tid,
        process: Tid,
        old_mm: MmId,
        errno: Errno,
        backend_refuses: bool,
        refusal: Option<reverie::UnsupportedRefusal>,
        refusal_takes: usize,
        injections: usize,
        requests: Mutex<Vec<GlobalRequest>>,
    }

    #[reverie::tool]
    impl GlobalRPC<GlobalState> for FailedExecGuest<'_> {
        async fn send_rpc(
            &self,
            message: <GlobalState as GlobalTool>::Request,
        ) -> <GlobalState as GlobalTool>::Response {
            assert_eq!(message.1, self.old_mm, "RPC follows restored exec identity");
            self.requests.lock().unwrap().push(message.2.clone());
            self.global.receive_rpc(self.sender, message).await
        }
        fn config(&self) -> &Config {
            self.config
        }
    }

    #[reverie::tool]
    impl Guest<Detcore> for FailedExecGuest<'_> {
        type Memory = reverie::syscalls::LocalMemory;
        type Stack = FailedExecStack;

        fn tid(&self) -> Tid {
            self.sender
        }
        fn pid(&self) -> Tid {
            self.process
        }
        fn ppid(&self) -> Option<Tid> {
            None
        }
        fn memory(&self) -> Self::Memory {
            panic!("failed exec rollback must not read guest memory")
        }
        fn thread_state(&self) -> &crate::ThreadState<()> {
            &self.thread
        }
        fn thread_state_mut(&mut self) -> &mut crate::ThreadState<()> {
            &mut self.thread
        }
        async fn regs(&mut self) -> libc::user_regs_struct {
            panic!("failed exec rollback must not read registers")
        }
        async fn stack(&mut self) -> Self::Stack {
            panic!("failed exec rollback must not use a guest stack")
        }
        async fn daemonize(&mut self) {
            panic!("failed exec rollback must not daemonize")
        }
        async fn inject<S: SyscallInfo>(&mut self, call: S) -> Result<i64, Errno> {
            assert_eq!(call.number(), syscalls::Sysno::execveat);
            assert_eq!(
                self.thread.mm_id,
                self.old_mm.for_exec(self.thread.detpid.unwrap())
            );
            assert_eq!(self.thread.robust_list_head, None);
            self.injections += 1;
            // As reverie-kvm does, every injection replaces the record.
            self.refusal = self.backend_refuses.then(|| {
                reverie::UnsupportedRefusal::new(
                    reverie::UnsupportedOperation::NonLeaderExec,
                    self.errno,
                    "KVM nonleader exec is unsupported",
                )
            });
            Err(self.errno)
        }
        fn take_unsupported_refusal(&mut self) -> Option<reverie::UnsupportedRefusal> {
            assert_eq!(
                self.thread.mm_id,
                self.old_mm.for_exec(self.thread.detpid.unwrap()),
                "the refusal is taken before the failed exec is rolled back"
            );
            self.refusal_takes += 1;
            self.refusal.take()
        }
        async fn tail_inject<S: SyscallInfo>(&mut self, _: S) -> reverie::Never {
            panic!("failed exec must not retire a live guest")
        }
        fn set_timer(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
            panic!("failed exec rollback must not replace the timer")
        }
        fn set_timer_precise(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
            panic!("failed exec rollback must not replace the timer")
        }
        fn read_clock(&mut self) -> Result<u64, Error> {
            panic!("failed exec rollback must not sample the clock")
        }
    }

    #[tokio::test]
    async fn backend_exec_refusal_preserves_failed_exec_rollback_and_policy() {
        let process = DetPid::from_raw(17);
        let worker = DetTid::from_raw(18);
        // `backend_refuses` is whether the backend reports a typed refusal for
        // the exec. reverie-kvm reports one for every worker exec that returns
        // ENOSYS, whether its own refusal after preflight or an ENOSYS from a
        // host syscall the preflight makes: the first two rows. The last row
        // is a worker ENOSYS for which a backend with KVM's other behaviours
        // reports no refusal (as KvmGuest::inject's early admission refusals
        // do); Detcore must not infer a refusal from the errno, so it is an
        // ordinary exec failure.
        for (kvm_behaviours, caller, errno, backend_refuses, fail_closed, refused, reported) in [
            (true, worker, Errno::ENOSYS, true, true, true, false),
            (true, worker, Errno::ENOSYS, true, false, false, true),
            (true, worker, Errno::ENOENT, false, true, false, false),
            (true, worker, Errno::ENOEXEC, false, true, false, false),
            (true, worker, Errno::EFAULT, false, true, false, false),
            (true, worker, Errno::EACCES, false, true, false, false),
            (true, worker, Errno::EOPNOTSUPP, false, true, false, false),
            (true, process, Errno::ENOSYS, false, true, false, false),
            (false, worker, Errno::ENOSYS, false, true, false, false),
            (true, worker, Errno::ENOSYS, false, true, false, false),
        ] {
            let mut report = tempfile::tempfile().unwrap();
            let config = Config {
                sequentialize_threads: false,
                panic_on_unsupported_syscalls: fail_closed,
                exit_on_unsupported_syscall: true,
                shutdown_on_unsupported_syscall: false,
                unsupported_syscall_report_fd: Some(report.as_raw_fd()),
                ..Config::default().with_backend(|backend| {
                    if kvm_behaviours {
                        // The behaviours the old `backend_is_kvm` identity flag
                        // selected, other than the exec refusal, which the
                        // backend now reports per exec (`backend_refuses`), and
                        // the user address limit, which it reports per guest.
                        backend.provides_process_signal_control = true;
                        backend.emulates_child_waits = true;
                    }
                })
            };
            let global = GlobalState::init_global_state(&config).await;
            let tool = Detcore::new(Tid::from_raw(process.as_raw()), &config);
            let mut thread = crate::ThreadState::new(caller, &config, ());
            thread.detpid = Some(process);
            thread.mm_id = MmId::initial(process);
            thread.record_robust_list_head(Some(0x12340));
            thread.thread_logical_time.add_syscall_with_cost(123);
            let old_time = thread.thread_logical_time.as_nanos();
            let old_files = Arc::clone(&thread.file_metadata);
            let old_memory = Arc::clone(&thread.memory_metadata);
            let old_mm = thread.mm_id;
            let mut guest = FailedExecGuest {
                config: &config,
                global: &global,
                thread,
                sender: Tid::from_raw(caller.as_raw()),
                process: Tid::from_raw(process.as_raw()),
                old_mm,
                errno,
                backend_refuses,
                refusal: None,
                refusal_takes: 0,
                injections: 0,
                requests: Mutex::new(Vec::new()),
            };
            let result = tool
                .handle_execveat(&mut guest, syscalls::Execveat::new())
                .await;
            match result {
                Err(Error::Tool(error)) if refused => assert_eq!(
                    error
                        .downcast_ref::<crate::UnsupportedSyscallError>()
                        .unwrap()
                        .0,
                    syscalls::Sysno::execveat
                ),
                Err(Error::Errno(actual)) if !refused => assert_eq!(actual, errno),
                result => panic!("wrong failed-exec policy: {result:?}"),
            }
            assert_eq!(guest.injections, 1, "backend preflight must run first");
            assert_eq!(guest.refusal_takes, 1, "the refusal must be asked for once");
            assert_eq!(guest.refusal, None, "a reported refusal must be taken");
            assert_eq!(guest.thread.dettid, caller);
            assert_eq!(guest.thread.detpid, Some(process));
            assert_eq!(guest.thread.mm_id, old_mm);
            assert_eq!(guest.thread.robust_list_head, Some(0x12340));
            assert_eq!(guest.thread.thread_logical_time.as_nanos(), old_time);
            assert!(Arc::ptr_eq(&guest.thread.file_metadata, &old_files));
            assert!(Arc::ptr_eq(&guest.thread.memory_metadata, &old_memory));
            let requests = guest.requests.lock().unwrap();
            assert!(matches!(requests[0], GlobalRequest::PrepareExec(..)));
            assert!(matches!(requests[1], GlobalRequest::CancelExec(..)));
            assert_eq!(requests.len(), if reported { 3 } else { 2 });
            if reported {
                assert!(
                    matches!(&requests[2], GlobalRequest::ReportUnsupportedSyscall(name) if name == "execveat")
                );
            }
            report.rewind().unwrap();
            let mut aggregate = String::new();
            report.read_to_string(&mut aggregate).unwrap();
            assert_eq!(aggregate, if reported { "execveat\n" } else { "" });
        }
    }

    /// A guest whose backend fails every clone with `errno`, recording a typed
    /// refusal when `backend_refuses`, as an in-guest backend does for a
    /// thread it cannot create.
    struct FailedCloneGuest<'a> {
        config: &'a Config,
        global: &'a GlobalState,
        thread: crate::ThreadState<()>,
        sender: Tid,
        errno: Errno,
        backend_refuses: bool,
        refusal: Option<reverie::UnsupportedRefusal>,
        refusal_takes: usize,
        injections: usize,
        requests: Mutex<Vec<GlobalRequest>>,
    }

    #[reverie::tool]
    impl GlobalRPC<GlobalState> for FailedCloneGuest<'_> {
        async fn send_rpc(
            &self,
            message: <GlobalState as GlobalTool>::Request,
        ) -> <GlobalState as GlobalTool>::Response {
            self.requests.lock().unwrap().push(message.2.clone());
            self.global.receive_rpc(self.sender, message).await
        }
        fn config(&self) -> &Config {
            self.config
        }
    }

    #[reverie::tool]
    impl Guest<Detcore> for FailedCloneGuest<'_> {
        type Memory = reverie::syscalls::LocalMemory;
        type Stack = FailedExecStack;

        fn tid(&self) -> Tid {
            self.sender
        }
        fn pid(&self) -> Tid {
            self.sender
        }
        fn ppid(&self) -> Option<Tid> {
            None
        }
        fn memory(&self) -> Self::Memory {
            reverie::syscalls::LocalMemory::new()
        }
        fn thread_state(&self) -> &crate::ThreadState<()> {
            &self.thread
        }
        fn thread_state_mut(&mut self) -> &mut crate::ThreadState<()> {
            &mut self.thread
        }
        async fn regs(&mut self) -> libc::user_regs_struct {
            panic!("a failed clone must not read registers")
        }
        async fn stack(&mut self) -> Self::Stack {
            panic!("a failed clone must not use a guest stack")
        }
        async fn daemonize(&mut self) {
            panic!("a failed clone must not daemonize")
        }
        async fn inject<S: SyscallInfo>(&mut self, call: S) -> Result<i64, Errno> {
            assert_eq!(call.number(), syscalls::Sysno::clone);
            self.injections += 1;
            self.refusal = self.backend_refuses.then(|| {
                reverie::UnsupportedRefusal::new(
                    reverie::UnsupportedOperation::NativeExec,
                    self.errno,
                    "this backend cannot create a thread",
                )
            });
            Err(self.errno)
        }
        fn take_unsupported_refusal(&mut self) -> Option<reverie::UnsupportedRefusal> {
            self.refusal_takes += 1;
            self.refusal.take()
        }
        async fn tail_inject<S: SyscallInfo>(&mut self, _: S) -> reverie::Never {
            panic!("a failed clone must not retire a live guest")
        }
        fn set_timer(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
            panic!("a failed clone must not replace the timer")
        }
        fn set_timer_precise(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
            panic!("a failed clone must not replace the timer")
        }
        fn read_clock(&mut self) -> Result<u64, Error> {
            panic!("a failed clone must not sample the clock")
        }
    }

    /// A clone the backend refuses with a typed refusal is refused by the
    /// unsupported-operation policy, never answered with the refusal's errno in
    /// a fail-closed run; a clone that merely fails keeps its errno.
    #[tokio::test]
    async fn backend_clone_refusal_follows_the_unsupported_operation_policy() {
        let process = DetPid::from_raw(23);
        for (errno, backend_refuses, fail_closed, refused, reported) in [
            (Errno::EOPNOTSUPP, true, true, true, false),
            (Errno::EOPNOTSUPP, true, false, false, true),
            (Errno::EAGAIN, false, true, false, false),
            (Errno::EOPNOTSUPP, false, true, false, false),
        ] {
            let mut report = tempfile::tempfile().unwrap();
            let config = Config {
                sequentialize_threads: false,
                panic_on_unsupported_syscalls: fail_closed,
                exit_on_unsupported_syscall: true,
                shutdown_on_unsupported_syscall: false,
                unsupported_syscall_report_fd: Some(report.as_raw_fd()),
                ..Config::default()
            };
            let global = GlobalState::init_global_state(&config).await;
            let tool = Detcore::new(Tid::from_raw(process.as_raw()), &config);
            let mut thread = crate::ThreadState::new(process, &config, ());
            thread.detpid = Some(process);
            let mut guest = FailedCloneGuest {
                config: &config,
                global: &global,
                thread,
                sender: Tid::from_raw(process.as_raw()),
                errno,
                backend_refuses,
                refusal: None,
                refusal_takes: 0,
                injections: 0,
                requests: Mutex::new(Vec::new()),
            };
            let flags = (libc::CLONE_VM
                | libc::CLONE_FS
                | libc::CLONE_FILES
                | libc::CLONE_SIGHAND
                | libc::CLONE_THREAD
                | libc::CLONE_SYSVSEM) as u64;
            let clone = syscalls::Clone::new()
                .with_flags(nix::sched::CloneFlags::from_bits_truncate(flags as _));
            let result = tool
                .handle_clone_family(&mut guest, syscalls::family::CloneFamily::Clone(clone))
                .await;
            match result {
                Err(Error::Tool(error)) if refused => assert_eq!(
                    error
                        .downcast_ref::<crate::UnsupportedSyscallError>()
                        .unwrap()
                        .0,
                    syscalls::Sysno::clone
                ),
                Err(Error::Errno(actual)) if !refused => assert_eq!(actual, errno),
                result => panic!("wrong failed-clone policy: {result:?}"),
            }
            assert_eq!(guest.injections, 1);
            assert_eq!(guest.refusal_takes, 1, "the refusal must be asked for once");
            assert_eq!(guest.refusal, None, "a reported refusal must be taken");
            assert_eq!(guest.thread.clone_flags, None);
            let requests = guest.requests.lock().unwrap();
            assert_eq!(
                requests
                    .iter()
                    .filter(|request| matches!(request, GlobalRequest::ReportUnsupportedSyscall(name) if name == "clone"))
                    .count(),
                usize::from(reported)
            );
            report.rewind().unwrap();
            let mut aggregate = String::new();
            report.read_to_string(&mut aggregate).unwrap();
            assert_eq!(aggregate, if reported { "clone\n" } else { "" });
        }
    }

    fn bits(signals: &[i32]) -> KernelSigset {
        signals
            .iter()
            .fold(0, |set, &signal| set | kernel_sigset_bit(signal))
    }

    #[test]
    fn a_precise_futex_wait_holds_a_committed_signal_only_if_a_host_timed_source_can_post_it() {
        let chld = kernel_sigset_bit(libc::SIGCHLD);
        let usr1 = kernel_sigset_bit(libc::SIGUSR1);
        // Nothing committed: SIGCHLD and the host-timed signals are held.
        assert_eq!(futex_wait_held_after_wake(0, 0), chld);
        assert_eq!(futex_wait_held_after_wake(usr1, 0), chld | usr1);
        // A committed SIGCHLD is not held (https://github.com/rrnewton/hermit/issues/4005).
        assert_eq!(futex_wait_held_after_wake(0, chld), 0);
        assert_eq!(futex_wait_held_after_wake(usr1, chld), usr1);
        // Unless a host-timed source can post it too, and a committed
        // host-timed signal stays held.
        assert_eq!(futex_wait_held_after_wake(chld, chld), chld);
        assert_eq!(futex_wait_held_after_wake(usr1, usr1 | chld), usr1);
    }

    #[test]
    fn kernel_signal_state_parses_proc_status() {
        let status = "Name:\tguest\nSigQ:\t1/1024\nSigPnd:\t0000000000000200\n\
                      ShdPnd:\t0000000000000400\nSigBlk:\t0000000000000800\n\
                      SigIgn:\t0000000000001000\nSigCgt:\t0000000000000400\n";
        assert_eq!(
            KernelSignalState::parse(status),
            Some(KernelSignalState {
                pending: bits(&[libc::SIGUSR1, libc::SIGSEGV]),
                thread_pending: bits(&[libc::SIGUSR1]),
                shared_pending: bits(&[libc::SIGSEGV]),
                blocked: bits(&[libc::SIGUSR2]),
                ignored: bits(&[libc::SIGPIPE]),
                caught: bits(&[libc::SIGSEGV]),
            })
        );
        // Every line is required: a missing one is not an empty set.
        assert_eq!(
            KernelSignalState::parse("SigPnd:\t0\nShdPnd:\t0\nSigBlk:\t0\nSigIgn:\t0\n"),
            None
        );
        assert_eq!(
            KernelSignalState::parse(
                "SigPnd:\tzz\nShdPnd:\t0\nSigBlk:\t0\nSigIgn:\t0\nSigCgt:\t0\n"
            ),
            None
        );
    }

    #[test]
    fn only_unblocked_caught_or_fatal_signals_interrupt_a_wait() {
        let state = KernelSignalState {
            pending: bits(&[
                libc::SIGUSR1,
                libc::SIGUSR2,
                libc::SIGPIPE,
                libc::SIGTERM,
                libc::SIGCHLD,
                libc::SIGWINCH,
                libc::SIGURG,
                libc::SIGCONT,
            ]),
            blocked: bits(&[libc::SIGUSR2]),
            ignored: bits(&[libc::SIGPIPE]),
            caught: bits(&[libc::SIGUSR1, libc::SIGUSR2, libc::SIGWINCH]),
            ..Default::default()
        };
        // Caught and unblocked (SIGUSR1, SIGWINCH) and default-fatal (SIGTERM) end the
        // wait; blocked (SIGUSR2), ignored (SIGPIPE), and default-ignored ones do not.
        assert_eq!(
            state.pending_interrupting(state.blocked, false),
            bits(&[libc::SIGUSR1, libc::SIGWINCH, libc::SIGTERM])
        );
        // The mask the guest had when the wait began decides, not the current one.
        assert_eq!(
            state.pending_interrupting(0, false),
            bits(&[libc::SIGUSR1, libc::SIGUSR2, libc::SIGWINCH, libc::SIGTERM])
        );
        let interrupting = state.interrupting(state.blocked);
        assert_ne!(interrupting & kernel_sigset_bit(libc::SIGKILL), 0);
        assert_ne!(interrupting & kernel_sigset_bit(libc::SIGSTOP), 0);
        assert_eq!(
            interrupting & kernel_sigset_bit(reverie::PERF_EVENT_SIGNAL as i32),
            0
        );
        assert_eq!(kernel_sigset_bit(0), 0);
        assert_eq!(kernel_sigset_bit(65), 0);
    }

    /// A wait whose restart starts its relative timeout again does not end for a
    /// default `SIGTSTP`, `SIGTTIN`, or `SIGTTOU`, which Linux discards in an
    /// orphaned process group; every other wait still does. `SIGSTOP`, a caught
    /// stop signal, and a fatal signal end both kinds, and an ignored stop signal
    /// ends neither (review of https://github.com/rrnewton/hermit/pull/3361 at
    /// `cbb36408`, finding 4).
    #[test]
    fn a_rearming_wait_is_not_ended_by_a_default_job_control_stop() {
        let stops = bits(&[libc::SIGTSTP, libc::SIGTTIN, libc::SIGTTOU]);
        let state = KernelSignalState {
            pending: stops | bits(&[libc::SIGSTOP, libc::SIGTERM]),
            ..Default::default()
        };
        assert_eq!(state.default_job_control_stops(), stops);
        assert_eq!(state.pending_interrupting(0, false), state.pending);
        assert_eq!(
            state.pending_interrupting(0, true),
            bits(&[libc::SIGSTOP, libc::SIGTERM])
        );
        let rearming = state.interrupting_wait(0, true);
        assert_eq!(rearming & stops, 0);
        assert_eq!(rearming, state.interrupting(0) & !stops);

        // A handler makes SIGTSTP an ordinary caught signal, and SIG_IGN takes
        // SIGTTIN out of every wait; SIGTTOU keeps its default action.
        let state = KernelSignalState {
            pending: stops,
            caught: bits(&[libc::SIGTSTP]),
            ignored: bits(&[libc::SIGTTIN]),
            ..Default::default()
        };
        assert_eq!(state.default_job_control_stops(), bits(&[libc::SIGTTOU]));
        assert_eq!(state.pending_interrupting(0, true), bits(&[libc::SIGTSTP]));
        assert_eq!(
            state.pending_interrupting(0, false),
            bits(&[libc::SIGTSTP, libc::SIGTTOU])
        );
        // The mask still decides first.
        assert_eq!(state.pending_interrupting(bits(&[libc::SIGTSTP]), true), 0);
    }

    #[test]
    fn kernel_blocked_mask_preserves_libc_signal_membership() {
        let mask = blocked_signal_mask();
        let mut libc_mask: libc::sigset_t = unsafe { std::mem::zeroed() };
        unsafe {
            libc::sigfillset(&mut libc_mask);
            libc::sigdelset(&mut libc_mask, reverie::PERF_EVENT_SIGNAL as i32);
        }
        for raw_signal in 1..=KernelSigset::BITS as i32 {
            assert_eq!(
                signal_is_blocked(&mask, SigWrapper(raw_signal)),
                unsafe { libc::sigismember(&libc_mask, raw_signal) == 1 },
                "signal {raw_signal} membership changed while converting to the kernel ABI"
            );
        }
    }

    #[test]
    fn clone_without_child_cleartid_does_not_register_the_pointer() {
        assert_eq!(
            child_tid_clear_address(CloneFlags::CLONE_CHILD_SETTID, 0x1234),
            0
        );
    }

    #[test]
    fn clone_with_child_cleartid_registers_the_pointer() {
        assert_eq!(
            child_tid_clear_address(CloneFlags::CLONE_CHILD_CLEARTID, 0x1234),
            0x1234
        );
    }

    #[test]
    fn linux_default_dispositions_that_do_not_interrupt_child_waits() {
        for signal in [libc::SIGCHLD, libc::SIGCONT, libc::SIGURG, libc::SIGWINCH] {
            assert!(signal_default_disposition_does_not_interrupt_child_wait(
                SigWrapper(signal)
            ));
        }
        for signal in [libc::SIGALRM, libc::SIGSTOP, libc::SIGUSR1] {
            assert!(!signal_default_disposition_does_not_interrupt_child_wait(
                SigWrapper(signal)
            ));
        }
    }

    /// Only a serialized run on a backend whose kernel signal state is the
    /// guest's own, with no gdbserver attached, retires threads at a fatal
    /// delivery.
    #[test]
    fn only_serialized_ptrace_runs_without_a_gdbserver_retire_at_a_fatal_delivery() {
        let ptrace = Config {
            sequentialize_threads: true,
            ..Config::default()
        }
        .with_backend(|backend| *backend = reverie::BackendCapabilities::PTRACE);
        assert!(retires_others_at_fatal_delivery(&ptrace));
        for (case, cfg) in [
            (
                "gdbserver",
                Config {
                    gdbserver: true,
                    ..ptrace.clone()
                },
            ),
            (
                "unserialized",
                Config {
                    sequentialize_threads: false,
                    ..ptrace.clone()
                },
            ),
            (
                "DBT",
                ptrace
                    .clone()
                    .with_backend(|backend| *backend = reverie::BackendCapabilities::DBT),
            ),
        ] {
            assert!(!retires_others_at_fatal_delivery(&cfg), "{case}");
        }
    }

    /// A delivery stop's signal ends the process only when it is unblocked
    /// and left at a default that terminates or dumps core.
    #[test]
    fn only_an_unblocked_default_fatal_delivery_ends_the_process() {
        let abrt = kernel_sigset_bit(libc::SIGABRT);
        let default = KernelSignalState::default();
        assert!(default.delivery_carries_out_a_fatal_default(libc::SIGABRT));
        assert!(default.delivery_carries_out_a_fatal_default(libc::SIGSEGV));
        for signal in [libc::SIGCHLD, libc::SIGWINCH, libc::SIGTSTP, libc::SIGCONT] {
            assert!(
                !default.delivery_carries_out_a_fatal_default(signal),
                "{signal}"
            );
        }
        for state in [
            KernelSignalState {
                blocked: abrt,
                ..Default::default()
            },
            KernelSignalState {
                caught: abrt,
                ..Default::default()
            },
            KernelSignalState {
                ignored: abrt,
                ..Default::default()
            },
        ] {
            assert!(
                !state.delivery_carries_out_a_fatal_default(libc::SIGABRT),
                "{state:?}"
            );
        }
    }

    /// signal(7): the signals whose default action is to terminate or dump
    /// core end the process; those ignored, stopping or continuing by
    /// default do not, and SIGKILL never reaches a delivery callback
    /// (https://github.com/rrnewton/hermit/issues/4278).
    #[test]
    fn default_actions_that_end_the_process() {
        for signal in [
            libc::SIGTERM,
            libc::SIGINT,
            libc::SIGHUP,
            libc::SIGQUIT,
            libc::SIGABRT,
            libc::SIGSEGV,
            libc::SIGBUS,
            libc::SIGFPE,
            libc::SIGILL,
            libc::SIGPIPE,
            libc::SIGALRM,
            libc::SIGUSR1,
            libc::SIGUSR2,
            libc::SIGRTMIN(),
            libc::SIGRTMAX(),
        ] {
            assert!(
                signal_default_action_ends_the_process(SigWrapper(signal)),
                "{signal}"
            );
        }
        for signal in [
            libc::SIGCHLD,
            libc::SIGCONT,
            libc::SIGURG,
            libc::SIGWINCH,
            libc::SIGSTOP,
            libc::SIGTSTP,
            libc::SIGTTIN,
            libc::SIGTTOU,
            libc::SIGKILL,
        ] {
            assert!(
                !signal_default_action_ends_the_process(SigWrapper(signal)),
                "{signal}"
            );
        }
    }

    #[test]
    fn uncatchable_signals_do_not_require_a_sigaction_query() {
        assert!(signal_has_uncatchable_default_disposition(SigWrapper(
            libc::SIGKILL
        )));
        assert!(signal_has_uncatchable_default_disposition(SigWrapper(
            libc::SIGSTOP
        )));
        assert!(!signal_has_uncatchable_default_disposition(SigWrapper(
            libc::SIGUSR1
        )));
    }

    #[test]
    fn waitid_ready_child_wins_when_scheduler_also_reports_a_signal() {
        assert_eq!(
            exact_wait_poll_decision(true, true, Some(ExactChildWaitState::Running)),
            ExactWaitPollDecision::ChildReady
        );
        assert_eq!(
            exact_wait_poll_decision(false, true, Some(ExactChildWaitState::LogicallyExited)),
            ExactWaitPollDecision::ReapAfterLogicalExit
        );
        assert_eq!(
            exact_wait_poll_decision(false, true, Some(ExactChildWaitState::PhysicalExitPending)),
            ExactWaitPollDecision::AwaitPhysicalExit
        );
        assert_eq!(
            exact_wait_poll_decision(false, true, Some(ExactChildWaitState::Running)),
            ExactWaitPollDecision::Interrupted
        );
        assert_eq!(
            exact_wait_poll_decision(false, false, Some(ExactChildWaitState::Running)),
            ExactWaitPollDecision::Retry
        );
    }

    #[test]
    fn wait4_argument_validation_follows_linux_precedence() {
        let valid_bits = [0, 1, 3, 29, 30, 31];
        for bit in valid_bits {
            let options = WaitPidFlag::from_bits_retain((1_u32 << bit) as libc::c_int);
            assert_eq!(validate_wait4_arguments(-1, options), Ok(()), "bit {bit}");
        }

        for bit in (0..u32::BITS).filter(|bit| !valid_bits.contains(bit)) {
            let options = WaitPidFlag::from_bits_retain((1_u32 << bit) as libc::c_int);
            assert_eq!(
                validate_wait4_arguments(-1, options),
                Err(Errno::EINVAL),
                "bit {bit}"
            );
        }

        // Only INT_MIN is refused: every other pid, including the nearest
        // process-group selector, must still reach the wait.
        for pid in [libc::pid_t::MIN + 1, -2, 0, 1, libc::pid_t::MAX] {
            assert_eq!(
                validate_wait4_arguments(pid, WaitPidFlag::empty()),
                Ok(()),
                "pid {pid}"
            );
        }
        assert_eq!(
            validate_wait4_arguments(libc::pid_t::MIN, WaitPidFlag::empty()),
            Err(Errno::ESRCH)
        );
        assert_eq!(
            validate_wait4_arguments(libc::pid_t::MIN, WaitPidFlag::from_bits_retain(0x10)),
            Err(Errno::EINVAL),
            "invalid options must win over the INT_MIN selector"
        );
    }

    #[test]
    fn stale_any_child_preserves_interrupt_until_no_ready_child_remains() {
        let next_child = DetPid::from_raw(200);

        assert!(
            !stale_any_wait_must_interrupt(true, Some(next_child)),
            "another ready child must retain child-ready precedence"
        );
        assert!(
            stale_any_wait_must_interrupt(true, None),
            "a pending signal must interrupt before the wait parks again"
        );
        assert!(!stale_any_wait_must_interrupt(false, None));
    }

    #[test]
    fn ioprio_query_reports_fixed_raw_and_effective_defaults() {
        assert_eq!(virtual_ioprio(IOPRIO_WHO_PROCESS), Ok(0));
        assert_eq!(
            virtual_ioprio(IOPRIO_WHO_PGRP),
            Ok(i64::from(IOPRIO_DEFAULT_EFFECTIVE))
        );
        assert_eq!(
            virtual_ioprio(IOPRIO_WHO_USER),
            Ok(i64::from(IOPRIO_DEFAULT_EFFECTIVE))
        );
        assert_eq!(virtual_ioprio(0), Err(Errno::EINVAL));
        assert_eq!(virtual_ioprio(4), Err(Errno::EINVAL));
    }

    #[test]
    fn waitid_siginfo_canonicalization_clears_only_cpu_accounting() {
        let mut info: libc::siginfo_t = unsafe { std::mem::zeroed() };
        info.si_signo = libc::SIGCHLD;
        info.si_code = libc::CLD_EXITED;
        // SAFETY: This uses the same Linux SIGCHLD layout mirror validated by
        // canonicalize_waitid_siginfo.
        let fields = unsafe {
            &mut (*(std::ptr::addr_of_mut!(info)).cast::<WaitidSiginfoHead>())
                .fields
                .sigchld
        };
        fields.pid = 123;
        fields.uid = 456;
        fields.status = 7;
        fields.utime = 8;
        fields.stime = 9;

        canonicalize_waitid_siginfo(&mut info);

        assert_eq!(info.si_signo, libc::SIGCHLD);
        assert_eq!(info.si_code, libc::CLD_EXITED);
        assert_eq!(unsafe { info.si_pid() }, 123);
        assert_eq!(unsafe { info.si_uid() }, 456);
        assert_eq!(unsafe { info.si_status() }, 7);
        assert_eq!(unsafe { info.si_utime() }, 0);
        assert_eq!(unsafe { info.si_stime() }, 0);
    }

    #[test]
    fn wait_status_rollup_only_accepts_process_termination() {
        assert!(wait_status_is_termination(0));
        assert!(wait_status_is_termination(libc::SIGTERM));
        assert!(!wait_status_is_termination((libc::SIGSTOP << 8) | 0x7f));
        assert!(!wait_status_is_termination(0xffff));

        assert!(waitid_code_is_termination(libc::CLD_EXITED));
        assert!(waitid_code_is_termination(libc::CLD_KILLED));
        assert!(waitid_code_is_termination(libc::CLD_DUMPED));
        assert!(!waitid_code_is_termination(libc::CLD_STOPPED));
        assert!(!waitid_code_is_termination(libc::CLD_CONTINUED));
        assert!(!waitid_code_is_termination(libc::CLD_TRAPPED));
    }

    /// `do_futex` (kernel/futex/syscalls.c): FUTEX_CLOCK_REALTIME only with
    /// FUTEX_WAIT_BITSET, FUTEX_WAIT_REQUEUE_PI or FUTEX_LOCK_PI2, else -ENOSYS;
    /// the removed FUTEX_FD and unknown commands are -ENOSYS; the requeue-PI
    /// commands are refused by name; the rest, the PI lock commands included,
    /// are emulated (https://github.com/rrnewton/hermit/issues/3958).
    #[test]
    fn futex_commands_are_classified_as_linux_dispatches_them() {
        use FutexCommand::*;
        let private = libc::FUTEX_PRIVATE_FLAG;
        let realtime = libc::FUTEX_CLOCK_REALTIME;
        for cmd in [
            libc::FUTEX_WAIT,
            libc::FUTEX_WAIT_BITSET,
            libc::FUTEX_WAKE,
            libc::FUTEX_WAKE_BITSET,
            libc::FUTEX_REQUEUE,
            libc::FUTEX_CMP_REQUEUE,
            libc::FUTEX_WAKE_OP,
        ] {
            assert_eq!(classify_futex_command(cmd), Served, "cmd {cmd}");
            assert_eq!(classify_futex_command(cmd | private), Served, "cmd {cmd}");
        }
        assert_eq!(
            classify_futex_command(libc::FUTEX_WAIT_BITSET | realtime),
            Served
        );
        for cmd in [
            libc::FUTEX_WAIT,
            libc::FUTEX_WAKE,
            libc::FUTEX_REQUEUE,
            libc::FUTEX_WAKE_OP,
        ] {
            assert_eq!(classify_futex_command(cmd | realtime), NoSys, "cmd {cmd}");
        }
        for cmd in [libc::FUTEX_FD, 14, 99, libc::FUTEX_CMD_MASK] {
            assert_eq!(classify_futex_command(cmd), NoSys, "cmd {cmd}");
        }
        for cmd in [
            libc::FUTEX_LOCK_PI,
            libc::FUTEX_LOCK_PI2,
            libc::FUTEX_TRYLOCK_PI,
            libc::FUTEX_UNLOCK_PI,
        ] {
            assert_eq!(classify_futex_command(cmd), Served, "cmd {cmd}");
            assert_eq!(classify_futex_command(cmd | private), Served, "cmd {cmd}");
        }
        assert_eq!(
            classify_futex_command(libc::FUTEX_LOCK_PI2 | realtime),
            Served
        );
        for cmd in [
            libc::FUTEX_LOCK_PI,
            libc::FUTEX_TRYLOCK_PI,
            libc::FUTEX_UNLOCK_PI,
        ] {
            assert_eq!(classify_futex_command(cmd | realtime), NoSys, "cmd {cmd}");
        }
        assert_eq!(
            classify_futex_command(libc::FUTEX_WAIT_REQUEUE_PI | realtime),
            RequeuePi("FUTEX_WAIT_REQUEUE_PI")
        );
        for (cmd, name) in [
            (libc::FUTEX_WAIT_REQUEUE_PI, "FUTEX_WAIT_REQUEUE_PI"),
            (libc::FUTEX_CMP_REQUEUE_PI, "FUTEX_CMP_REQUEUE_PI"),
        ] {
            assert_eq!(classify_futex_command(cmd), RequeuePi(name));
        }
        assert_eq!(
            classify_futex_command(libc::FUTEX_CMP_REQUEUE_PI | realtime),
            NoSys
        );
    }

    /// `futex_init_timeout` and `do_futex` (kernel/futex/syscalls.c:114-116,
    /// 147-157 at v6.16): FUTEX_WAIT's timeout is relative; FUTEX_WAIT_BITSET's,
    /// FUTEX_LOCK_PI's and FUTEX_LOCK_PI2's are absolute. FUTEX_LOCK_PI's is
    /// always on CLOCK_REALTIME, the others' only with FUTEX_CLOCK_REALTIME.
    #[test]
    fn futex_deadlines_are_measured_as_linux_measures_them() {
        let one_second = Timespec {
            tv_sec: 1,
            tv_nsec: 0,
        };
        let realtime = libc::FUTEX_CLOCK_REALTIME;
        assert_eq!(
            parse_futex_timeout(libc::FUTEX_WAIT, one_second),
            Ok(FutexTimeout::Relative(1_000_000_000))
        );
        for cmd in [
            libc::FUTEX_WAIT_BITSET,
            libc::FUTEX_LOCK_PI,
            libc::FUTEX_LOCK_PI2,
            libc::FUTEX_LOCK_PI | libc::FUTEX_PRIVATE_FLAG,
        ] {
            assert_eq!(
                parse_futex_timeout(cmd, one_second),
                Ok(FutexTimeout::Absolute(LogicalTime::from_nanos(
                    1_000_000_000
                ))),
                "cmd {cmd}"
            );
        }
        assert_eq!(
            futex_deadline_clock(libc::FUTEX_LOCK_PI),
            syscalls::ClockId::CLOCK_REALTIME
        );
        assert_eq!(
            futex_deadline_clock(libc::FUTEX_LOCK_PI2),
            syscalls::ClockId::CLOCK_MONOTONIC
        );
        assert_eq!(
            futex_deadline_clock(libc::FUTEX_LOCK_PI2 | realtime),
            syscalls::ClockId::CLOCK_REALTIME
        );
        assert_eq!(
            futex_deadline_clock(libc::FUTEX_WAIT_BITSET),
            syscalls::ClockId::CLOCK_MONOTONIC
        );
    }

    /// FUTEX_WAKE_OP's encoding, as `futex_atomic_op_inuser` decodes it: 12-bit
    /// signed arguments, the shift flag (with an out-of-range shift masked to
    /// 0..31), and -ENOSYS for an unknown operation or comparison.
    /// An injected probe's futex op, uaddr, uaddr2, val and val3.
    type ProbeArgs = (i32, usize, usize, i32, i32);

    /// A guest standing in for the kernel: each injected probe is recorded and
    /// answered with the next scripted result.
    struct ScriptedProbes {
        answers: std::collections::VecDeque<Result<i64, Errno>>,
        probes: Vec<ProbeArgs>,
    }

    impl ScriptedProbes {
        fn inject(&mut self, probe: syscalls::Futex) -> KeyProbeAnswer<'_> {
            self.probes.push((
                probe.futex_op(),
                probe.uaddr().map_or(0, AddrMut::as_raw),
                probe.uaddr2().map_or(0, AddrMut::as_raw),
                probe.val(),
                probe.val3(),
            ));
            let answer = self
                .answers
                .pop_front()
                .expect("the probe was injected more often than scripted");
            Box::pin(async move { answer })
        }
    }

    fn run_scripted(
        access: KeyAccess,
        answer: Result<i64, Errno>,
    ) -> (SharedKeyProbe, Vec<ProbeArgs>) {
        let mut guest = ScriptedProbes {
            answers: [answer].into_iter().collect(),
            probes: Vec::new(),
        };
        let result = futures::executor::block_on(run_shared_futex_key_probe(
            &mut guest,
            shared_futex_key_probe(0x1000, access),
            access,
            |guest, probe| guest.inject(probe),
        ));
        (result, guest.probes)
    }

    /// The shared-key admission probe is injected exactly once
    /// (https://github.com/rrnewton/hermit/pull/4020). When a signal stops it
    /// before it runs (`Guest::inject` returns ERESTARTSYS, or EINTR), it is not
    /// injected again, because Reverie holds that signal in a single slot that a
    /// second interruption would overwrite, and the interruption is reported as
    /// such: never as an admitted key and never as the guest's errno. The
    /// caller stops the run by name on it. The kernel's own answers keep their
    /// meaning: 0 admits, ENOSYS admits only a WRITE key, EFAULT is the
    /// guest's.
    #[test]
    fn an_interrupted_shared_key_probe_is_never_retried_or_taken_as_an_answer() {
        let read = (libc::FUTEX_REQUEUE, 0x1000, 0x1000, 0, 0);
        let write = (
            libc::FUTEX_WAKE_OP,
            0x1000,
            0x1000,
            0,
            (7 << 28) | (1 << 12),
        );
        for (access, args) in [(KeyAccess::Read, read), (KeyAccess::Write, write)] {
            for errno in [Errno::ERESTARTSYS, Errno::EINTR] {
                assert_eq!(
                    run_scripted(access, Err(errno)),
                    (SharedKeyProbe::Interrupted(errno), vec![args]),
                    "{access:?} {errno}"
                );
            }
            assert_eq!(
                run_scripted(access, Ok(0)),
                (SharedKeyProbe::Admitted, vec![args])
            );
            assert_eq!(
                run_scripted(access, Err(Errno::EFAULT)),
                (SharedKeyProbe::Refused(Errno::EFAULT), vec![args])
            );
        }
        assert_eq!(
            run_scripted(KeyAccess::Read, Err(Errno::ENOSYS)),
            (SharedKeyProbe::Refused(Errno::ENOSYS), vec![read])
        );
        assert_eq!(
            run_scripted(KeyAccess::Write, Err(Errno::ENOSYS)),
            (SharedKeyProbe::Admitted, vec![write])
        );
    }

    #[test]
    fn futex_wake_op_decodes_and_applies_as_linux() {
        let encode = |op: u32, cmp: u32, oparg: u32, cmparg: u32| {
            ((op & 0xf) << 28) | ((cmp & 0xf) << 24) | ((oparg & 0xfff) << 12) | (cmparg & 0xfff)
        };
        let set5_eq0 = FutexWakeOp::decode(encode(FUTEX_OP_SET, FUTEX_OP_CMP_EQ, 5, 0));
        assert_eq!(set5_eq0.apply(0), Some(5));
        assert_eq!(set5_eq0.compare(0), Some(true));
        assert_eq!(set5_eq0.compare(1), Some(false));
        let add_minus1 = FutexWakeOp::decode(encode(FUTEX_OP_ADD, FUTEX_OP_CMP_LT, 0xfff, 0x800));
        assert_eq!(add_minus1.apply(10), Some(9));
        assert_eq!(add_minus1.apply(i32::MIN), Some(i32::MAX));
        assert_eq!(add_minus1.compare(-2048), Some(false));
        assert_eq!(add_minus1.compare(-2049), Some(true));
        let or = FutexWakeOp::decode(encode(FUTEX_OP_OR, FUTEX_OP_CMP_NE, 0b100, 7));
        assert_eq!(or.apply(0b011), Some(0b111));
        assert_eq!(or.compare(7), Some(false));
        let andn = FutexWakeOp::decode(encode(FUTEX_OP_ANDN, FUTEX_OP_CMP_GE, 0b110, 3));
        assert_eq!(andn.apply(0b111), Some(0b001));
        assert_eq!(andn.compare(3), Some(true));
        let xor = FutexWakeOp::decode(encode(FUTEX_OP_XOR, FUTEX_OP_CMP_LE, 0xff, 0));
        assert_eq!(xor.apply(0x0f), Some(0xf0));
        assert_eq!(xor.compare(1), Some(false));
        let shift = FutexWakeOp::decode(encode(
            FUTEX_OP_OPARG_SHIFT | FUTEX_OP_OR,
            FUTEX_OP_CMP_GT,
            3,
            0,
        ));
        assert_eq!(shift.apply(0), Some(8));
        assert_eq!(shift.compare(1), Some(true));
        // A shift of -1 (0xfff) is masked to 31, as Linux does.
        let masked = FutexWakeOp::decode(encode(FUTEX_OP_OPARG_SHIFT | FUTEX_OP_SET, 0, 0xfff, 0));
        assert_eq!(masked.apply(0), Some(i32::MIN));
        let unknown_op = FutexWakeOp::decode(encode(7, FUTEX_OP_CMP_EQ, 1, 0));
        assert!(!unknown_op.has_known_operation());
        assert_eq!(unknown_op.apply(0), None);
        let unknown_cmp = FutexWakeOp::decode(encode(FUTEX_OP_SET, 6, 1, 0));
        assert!(unknown_cmp.has_known_operation());
        assert_eq!(unknown_cmp.compare(0), None);
    }

    #[test]
    fn futex_timeout_units_and_modes_match_linux() {
        let timeout = Timespec {
            tv_sec: 2,
            tv_nsec: 3,
        };
        assert_eq!(
            parse_futex_timeout(libc::FUTEX_WAIT, timeout),
            Ok(FutexTimeout::Relative(2_000_000_003))
        );
        assert_eq!(
            parse_futex_timeout(libc::FUTEX_WAIT_BITSET, timeout),
            Ok(FutexTimeout::Absolute(LogicalTime::from_nanos(
                2_000_000_003
            )))
        );
        // The command bits must be matched after masking off FUTEX_PRIVATE_FLAG
        // (and FUTEX_CLOCK_REALTIME): a private FUTEX_WAIT_BITSET still uses an
        // absolute deadline, and a private FUTEX_WAIT still uses a relative one.
        assert_eq!(
            parse_futex_timeout(libc::FUTEX_WAIT_BITSET | libc::FUTEX_PRIVATE_FLAG, timeout),
            Ok(FutexTimeout::Absolute(LogicalTime::from_nanos(
                2_000_000_003
            )))
        );
        assert_eq!(
            parse_futex_timeout(libc::FUTEX_WAIT | libc::FUTEX_PRIVATE_FLAG, timeout),
            Ok(FutexTimeout::Relative(2_000_000_003))
        );
    }

    #[test]
    fn absolute_futex_timeout_is_rebased_to_logical_time() {
        let logical_now = LogicalTime::from_secs(100);
        let clock_now = LogicalTime::from_secs(5_000);
        let deadline = clock_now + Duration::from_millis(100);
        assert_eq!(
            rebase_absolute_timeout(deadline, clock_now, logical_now),
            logical_now + Duration::from_millis(100)
        );
        assert_eq!(
            rebase_absolute_timeout(
                clock_now - LogicalTime::from_nanos(1),
                clock_now,
                logical_now
            ),
            logical_now
        );
    }

    #[test]
    fn absolute_futex_timeout_detects_host_and_logical_clock_domains() {
        let host_monotonic_now = LogicalTime::from_secs(374_766);
        let logical_now = LogicalTime::from_secs(1_640_995_199);
        let delta = Duration::from_millis(100);

        assert!(absolute_timeout_uses_host_clock(
            host_monotonic_now + delta,
            host_monotonic_now,
            logical_now
        ));
        assert!(!absolute_timeout_uses_host_clock(
            logical_now + delta,
            host_monotonic_now,
            logical_now
        ));

        let host_realtime_now = LogicalTime::from_secs(1_785_142_800);
        assert!(absolute_timeout_uses_host_clock(
            host_realtime_now + delta,
            host_realtime_now,
            logical_now
        ));
    }

    /// Linux's `futex_init_timeout` refuses only an invalid timespec, and
    /// `timespec64_to_ktime` clamps a valid one beyond `KTIME_MAX` instead of
    /// refusing it (Codex re-check of https://github.com/rrnewton/hermit/pull/4061).
    #[test]
    fn futex_timeout_clamps_a_huge_valid_timespec_like_ktime() {
        let huge = Timespec {
            tv_sec: libc::time_t::MAX,
            tv_nsec: 0,
        };
        assert!(futex_timespec_is_valid(huge));
        assert_eq!(
            parse_futex_timeout(libc::FUTEX_WAIT, huge),
            Ok(FutexTimeout::Relative(FUTEX_KTIME_MAX_NANOS))
        );
        assert_eq!(
            parse_futex_timeout(libc::FUTEX_WAIT_BITSET, huge),
            Ok(FutexTimeout::Absolute(LogicalTime::from_nanos(
                FUTEX_KTIME_MAX_NANOS
            )))
        );
        let at_ktime_sec_max = Timespec {
            tv_sec: (FUTEX_KTIME_MAX_NANOS / 1_000_000_000) as libc::time_t,
            tv_nsec: 0,
        };
        assert_eq!(
            parse_futex_timeout(libc::FUTEX_WAIT, at_ktime_sec_max),
            Ok(FutexTimeout::Relative(FUTEX_KTIME_MAX_NANOS))
        );
        let just_below = Timespec {
            tv_sec: (FUTEX_KTIME_MAX_NANOS / 1_000_000_000 - 1) as libc::time_t,
            tv_nsec: 999_999_999,
        };
        assert_eq!(
            parse_futex_timeout(libc::FUTEX_WAIT, just_below),
            Ok(FutexTimeout::Relative(
                (FUTEX_KTIME_MAX_NANOS / 1_000_000_000) * 1_000_000_000 - 1
            ))
        );
        for invalid in [(-1, 0), (0, -1), (0, 1_000_000_000)] {
            assert!(!futex_timespec_is_valid(Timespec {
                tv_sec: invalid.0,
                tv_nsec: invalid.1,
            }));
        }
    }

    #[test]
    fn futex_timeout_rejects_invalid_timespecs() {
        assert_eq!(
            parse_futex_timeout(
                libc::FUTEX_WAIT,
                Timespec {
                    tv_sec: -1,
                    tv_nsec: 0,
                },
            ),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            parse_futex_timeout(
                libc::FUTEX_WAIT_BITSET,
                Timespec {
                    tv_sec: 0,
                    tv_nsec: 1_000_000_000,
                },
            ),
            Err(Errno::EINVAL)
        );
    }

    // The expectations below are not guesses at the kernel's behaviour: each is
    // a row measured natively on this host (Linux 6.19, x86-64) with a raw
    // `sched_setattr` probe. Where a row differs from what the handler used to
    // do, the difference is called out.

    /// A well-formed VER0 SCHED_OTHER descriptor, as the decoded fields.
    fn plain_attr() -> SchedAttrFields {
        SchedAttrFields {
            policy: 0,
            sched_flags: 0,
            priority: 0,
            runtime: 0,
            deadline: 0,
            period: 0,
        }
    }

    #[test]
    fn size_zero_is_a_well_formed_ver0_request() {
        // ABI compatibility quirk: `if (!size) size = SCHED_ATTR_SIZE_VER0;`.
        // Measured native: ret 0. PR #2288 returned E2BIG.
        assert_eq!(sched_attr_effective_size(0), Ok(SCHED_ATTR_SIZE_VER0));
    }

    #[test]
    fn size_below_ver0_or_past_a_page_is_too_big() {
        // Measured native: size 1, 47 and 4097 all give E2BIG.
        assert_eq!(sched_attr_effective_size(1), Err(()));
        assert_eq!(sched_attr_effective_size(SCHED_ATTR_SIZE_VER0 - 1), Err(()));
        assert_eq!(
            sched_attr_effective_size(sched_attr_max_size() + 1),
            Err(())
        );
    }

    #[test]
    fn size_from_ver0_through_one_page_is_accepted_unchanged() {
        // Measured native: 48, 56, 57 and 4096 all give ret 0.
        for size in [
            SCHED_ATTR_SIZE_VER0,
            SCHED_ATTR_SIZE_VER1,
            SCHED_ATTR_SIZE_VER1 + 1,
            sched_attr_max_size(),
        ] {
            assert_eq!(sched_attr_effective_size(size), Ok(size), "size {}", size);
        }
    }

    #[test]
    fn sched_ext_is_a_valid_policy_and_sched_iso_is_not() {
        // Measured native: policy 7 gives ret 0; policy 4 gives EINVAL. PR
        // #2288 refused 7.
        assert!(is_valid_sched_policy(SCHED_EXT), "SCHED_EXT is accepted");
        assert!(!is_valid_sched_policy(4), "SCHED_ISO is reserved");
        for policy in [0, 1, 2, 3, 5, 6] {
            assert!(is_valid_sched_policy(policy), "policy {}", policy);
        }
        // Measured native: policy 8 and 99 both give EINVAL.
        for policy in [8, 99] {
            assert!(!is_valid_sched_policy(policy), "policy {}", policy);
        }
    }

    // ---- which side of the pid lookup each rule falls on --------------------
    // The kernel resolves the pid between `sched_setattr()` and
    // `__sched_setscheduler()`, so a request naming a nonexistent pid reports
    // ESRCH for every rule on the far side and its own errno for every rule on
    // the near side. Measured natively with pid 0x3fffffff:
    //     bad sched_flags    -> ESRCH    (far side)
    //     bad priority       -> ESRCH    (far side)
    //     negative policy    -> EINVAL   (near side)
    //     util-clamp size 48 -> EINVAL   (near side)
    // The split between the two functions below is exactly that boundary.

    #[test]
    fn util_clamp_size_rule_is_decided_before_the_pid_lookup() {
        // Measured native: EINVAL even with a nonexistent pid.
        let mut attr = plain_attr();
        attr.sched_flags = SCHED_FLAG_UTIL_CLAMP_MIN;
        assert_eq!(
            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &attr),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER1, &attr),
            Ok(())
        );
        // ...and it is not re-decided on the far side.
        assert_eq!(validate_sched_attr_after_lookup(&attr), Ok(()));
    }

    #[test]
    fn a_negative_policy_is_decided_before_the_pid_lookup() {
        // Measured native: EINVAL even with a nonexistent pid, and EINVAL with
        // KEEP_POLICY too -- the signed test sits above the substitution.
        let mut attr = plain_attr();
        attr.policy = 0x8000_0000;
        assert_eq!(
            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &attr),
            Err(Errno::EINVAL)
        );
        attr.sched_flags = SCHED_FLAG_KEEP_POLICY;
        assert_eq!(
            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &attr),
            Err(Errno::EINVAL),
            "KEEP_POLICY must not hide a negative policy"
        );
    }

    #[test]
    fn policy_and_flag_rules_are_decided_after_the_pid_lookup() {
        // Measured native: with a nonexistent pid both of these report ESRCH,
        // so neither may be decided on the near side.
        let mut bad_policy = plain_attr();
        bad_policy.policy = 99;
        assert_eq!(
            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &bad_policy),
            Ok(()),
            "an undefined policy must survive the near side so ESRCH can win"
        );
        assert_eq!(
            validate_sched_attr_after_lookup(&bad_policy),
            Err(Errno::EINVAL)
        );

        let mut bad_flag = plain_attr();
        bad_flag.sched_flags = 0x80;
        assert_eq!(
            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &bad_flag),
            Ok(()),
            "an undefined sched_flags bit must survive the near side"
        );
        assert_eq!(
            validate_sched_attr_after_lookup(&bad_flag),
            Err(Errno::EINVAL)
        );
    }

    #[test]
    fn keep_policy_makes_the_policy_field_irrelevant() {
        // Measured native: policy 99 alone is EINVAL, but policy 99 with
        // SCHED_FLAG_KEEP_POLICY is ret 0 -- the kernel overwrites the field
        // with SETPARAM_POLICY and never runs valid_policy(). PR #2288 refused
        // it.
        let mut attr = plain_attr();
        attr.policy = 99;
        assert_eq!(validate_sched_attr_after_lookup(&attr), Err(Errno::EINVAL));
        attr.sched_flags = SCHED_FLAG_KEEP_POLICY;
        assert_eq!(validate_sched_attr_after_lookup(&attr), Ok(()));
    }

    #[test]
    fn defined_sched_flags_bits_are_accepted_and_undefined_ones_are_not() {
        // Measured native: sched_flags 0x80 gives EINVAL; RESET_ON_FORK,
        // KEEP_PARAMS, KEEP_ALL, RECLAIM and DL_OVERRUN are all ret 0 at
        // size 48. PR #2288 ignored sched_flags entirely.
        let mut attr = plain_attr();
        attr.sched_flags = 0x80;
        assert_eq!(validate_sched_attr_after_lookup(&attr), Err(Errno::EINVAL));
        for flag in [
            SCHED_FLAG_RESET_ON_FORK,
            SCHED_FLAG_RECLAIM,
            SCHED_FLAG_DL_OVERRUN,
            SCHED_FLAG_KEEP_PARAMS,
            SCHED_FLAG_KEEP_POLICY,
        ] {
            let mut ok = plain_attr();
            ok.sched_flags = flag;
            assert_eq!(
                validate_sched_attr_after_lookup(&ok),
                Ok(()),
                "flag {:#x}",
                flag
            );
        }
        // The whole mask at once is refused on the NEAR side, and for the
        // util-clamp size reason rather than the flag-validity one: measured
        // native EINVAL at size 48.
        let mut all = plain_attr();
        all.sched_flags = SCHED_FLAG_ALL;
        assert_eq!(
            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER0, &all),
            Err(Errno::EINVAL)
        );
        assert_eq!(
            validate_sched_attr_before_lookup(SCHED_ATTR_SIZE_VER1, &all),
            Ok(())
        );
        assert_eq!(validate_sched_attr_after_lookup(&all), Ok(()));
    }

    #[test]
    fn priority_must_agree_with_the_policy() {
        // The kernel states this as `rt_policy(policy) != (prio != 0)`.
        // Measured native, all EINVAL: OTHER/BATCH/IDLE with priority 1, and
        // FIFO/RR with priority 0. PR #2288 accepted every one of them.
        for policy in [0u32, 3, 5] {
            let mut attr = plain_attr();
            attr.policy = policy;
            attr.priority = 1;
            assert_eq!(
                validate_sched_attr_after_lookup(&attr),
                Err(Errno::EINVAL),
                "policy {} with priority 1",
                policy
            );
            attr.priority = 0;
            assert_eq!(
                validate_sched_attr_after_lookup(&attr),
                Ok(()),
                "policy {} with priority 0",
                policy
            );
        }
        for policy in [SCHED_FIFO, SCHED_RR] {
            let mut attr = plain_attr();
            attr.policy = policy;
            attr.priority = 0;
            assert_eq!(
                validate_sched_attr_after_lookup(&attr),
                Err(Errno::EINVAL),
                "rt policy {} with priority 0",
                policy
            );
            // A real-time priority is accepted here; whether the *caller* may
            // ask for it is EPERM, which depends on privilege and is not
            // emulated.
            attr.priority = 1;
            assert_eq!(validate_sched_attr_after_lookup(&attr), Ok(()));
        }
    }

    #[test]
    fn a_priority_past_max_rt_prio_is_refused() {
        // Measured native: FIFO with priority 100 is EINVAL rather than the
        // EPERM that priorities 1..=99 give, so the range test runs first.
        let mut attr = plain_attr();
        attr.policy = SCHED_FIFO;
        attr.priority = MAX_RT_PRIO;
        assert_eq!(validate_sched_attr_after_lookup(&attr), Err(Errno::EINVAL));
        attr.priority = MAX_RT_PRIO - 1;
        assert_eq!(validate_sched_attr_after_lookup(&attr), Ok(()));
    }

    #[test]
    fn deadline_parameters_are_checked() {
        // Measured native: SCHED_DEADLINE with all-zero parameters is EINVAL,
        // and with runtime > deadline is EINVAL. PR #2288 accepted both.
        let mut zeroed = plain_attr();
        zeroed.policy = SCHED_DEADLINE;
        assert_eq!(
            validate_sched_attr_after_lookup(&zeroed),
            Err(Errno::EINVAL),
            "all-zero deadline parameters"
        );

        let mut inverted = plain_attr();
        inverted.policy = SCHED_DEADLINE;
        inverted.runtime = 90_000_000;
        inverted.deadline = 30_000_000;
        inverted.period = 30_000_000;
        assert_eq!(
            validate_sched_attr_after_lookup(&inverted),
            Err(Errno::EINVAL),
            "runtime > deadline"
        );

        // Sane parameters pass the ABI rules. Natively this host answers EPERM,
        // which is a privilege question rather than an ABI one.
        let mut sane = plain_attr();
        sane.policy = SCHED_DEADLINE;
        sane.runtime = 10_000_000;
        sane.deadline = 30_000_000;
        sane.period = 30_000_000;
        assert_eq!(validate_sched_attr_after_lookup(&sane), Ok(()));
    }

    #[test]
    fn deadline_parameter_edges_follow_checkparam_dl() {
        // deadline == 0 is refused whatever else is set.
        assert!(!deadline_params_are_valid(1 << 20, 0, 0));
        // runtime below the DL_SCALE truncation floor (1 << 10) is refused.
        assert!(!deadline_params_are_valid((1 << 10) - 1, 1 << 20, 1 << 20));
        assert!(deadline_params_are_valid(1 << 10, 1 << 20, 1 << 20));
        // The MSB is reserved on both deadline and period.
        assert!(!deadline_params_are_valid(1 << 20, 1 << 63, 0));
        assert!(!deadline_params_are_valid(1 << 20, 1 << 20, 1 << 63));
        // A zero period means "same as the deadline", so this is runtime <=
        // deadline <= deadline and is accepted.
        assert!(deadline_params_are_valid(1 << 20, 1 << 21, 0));
        // deadline > period is refused.
        assert!(!deadline_params_are_valid(1 << 20, 1 << 22, 1 << 21));
    }

    #[test]
    fn the_size_written_back_on_refusal_is_the_kernel_struct_not_the_libc_mirror() {
        // Measured native: every E2BIG row leaves uattr->size holding 56, not
        // 48. Deriving that from the libc crate's `sched_attr` would report 48
        // and tell the guest to retry with a size the kernel already accepted.
        assert_eq!(SCHED_ATTR_KERNEL_SIZE, 56);
        assert_eq!(std::mem::size_of::<libc::sched_attr>(), 48);
        assert_ne!(
            SCHED_ATTR_KERNEL_SIZE as usize,
            std::mem::size_of::<libc::sched_attr>()
        );
    }

    /// A `MemoryAccess` whose readable region ends at `readable_len`, recording
    /// every read length it is asked for.
    struct BoundedMemory {
        bytes: Vec<u8>,
        readable_len: usize,
        reads: std::cell::RefCell<Vec<usize>>,
    }

    impl reverie::syscalls::MemoryAccess for BoundedMemory {
        fn read_vectored(
            &self,
            read_from: &[std::io::IoSlice<'_>],
            write_to: &mut [std::io::IoSliceMut<'_>],
        ) -> Result<usize, Errno> {
            let start = read_from[0].as_ptr() as usize;
            let want = read_from.iter().map(|slice| slice.len()).sum::<usize>();
            self.reads.borrow_mut().push(want);
            if start >= self.readable_len {
                return Err(Errno::EFAULT);
            }
            let avail = (self.readable_len - start).min(want);
            let mut copied = 0;
            for out in write_to.iter_mut() {
                if copied == avail {
                    break;
                }
                let take = out.len().min(avail - copied);
                out[..take].copy_from_slice(&self.bytes[start + copied..start + copied + take]);
                copied += take;
            }
            Ok(copied)
        }

        fn write_vectored(
            &mut self,
            _read_from: &[std::io::IoSlice<'_>],
            _write_to: &mut [std::io::IoSliceMut<'_>],
        ) -> Result<usize, Errno> {
            unimplemented!("this fixture never writes")
        }
    }

    fn bounded(bytes: Vec<u8>, readable_len: usize) -> BoundedMemory {
        BoundedMemory {
            bytes,
            readable_len,
            reads: std::cell::RefCell::new(Vec::new()),
        }
    }

    fn tail_base() -> AddrMut<'static, u8> {
        AddrMut::<u8>::from_raw(1).expect("nonzero base")
    }

    /// ITEM 2 REGRESSION, ORDERING HALF: a non-zero byte BEFORE an unreadable
    /// page is E2BIG, not EFAULT.
    ///
    /// `check_zeroed_user` scans forward and stops at the first thing it finds,
    /// so it never reaches the fault. Reading the whole tail up front and
    /// judging afterwards turns this into EFAULT and changes the errno the
    /// guest sees.
    #[test]
    fn a_nonzero_byte_before_a_fault_is_e2big_not_efault() {
        let off = SCHED_ATTR_KERNEL_SIZE as usize;
        let mut bytes = vec![0u8; off + 4096];
        bytes[off + 1] = 0xAA; // non-zero, well before the boundary
        let readable = off + 512; // everything past this faults
        let memory = bounded(bytes, readable);
        assert_eq!(
            scan_tail_is_zeroed(&memory, tail_base(), off, 4096),
            TailVerdict::NotZeroed,
            "a non-zero byte the scan reaches first must win over a later fault"
        );
    }

    /// ITEM 2 REGRESSION, the other side of the same order: a fault with
    /// nothing non-zero before it is EFAULT.
    #[test]
    fn a_fault_before_any_nonzero_byte_is_efault() {
        let off = SCHED_ATTR_KERNEL_SIZE as usize;
        let bytes = vec![0u8; off + 4096];
        let memory = bounded(bytes, off + 512);
        assert_eq!(
            scan_tail_is_zeroed(&memory, tail_base(), off, 4096),
            TailVerdict::Faulted,
            "an unreadable byte reached before anything non-zero must be EFAULT"
        );
    }

    /// ITEM 2 REGRESSION, PROTECTION HALF: never issue a read of eight bytes or
    /// fewer.
    ///
    /// safeptrace serves those through `PTRACE_PEEKDATA`, which reads a whole
    /// aligned word and bypasses guest page protections, so a small tail would
    /// be readable under Hermit where Linux reports EFAULT. The assertion is on
    /// the READ LENGTHS ASKED FOR, because that is the mechanism; the returned
    /// verdict cannot show it.
    #[test]
    fn tail_reads_are_never_small_enough_to_bypass_guest_protection() {
        let off = SCHED_ATTR_KERNEL_SIZE as usize;
        for tail_len in 1..=16usize {
            let bytes = vec![0u8; off + tail_len + 64];
            let memory = bounded(bytes, off + tail_len + 64);
            assert_eq!(
                scan_tail_is_zeroed(&memory, tail_base(), off, tail_len),
                TailVerdict::AllZero
            );
            let reads = memory.reads.borrow().clone();
            assert!(!reads.is_empty(), "tail_len {tail_len} issued no read");
            for length in reads {
                assert!(
                    length > std::mem::size_of::<u64>(),
                    "tail_len {tail_len} issued a {length}-byte read, which safeptrace \
                     serves with PTRACE_PEEKDATA and which therefore bypasses guest \
                     page protections"
                );
            }
        }
    }

    /// ITEM 3 REGRESSION: KEEP_POLICY reuses the CURRENT policy; it does not
    /// switch the policy-dependent rules off.
    ///
    /// Detcore's current policy is the one `handle_sched_getattr` reports for
    /// every thread, SCHED_OTHER, and a non-real-time policy requires priority
    /// 0. Skipping the rules accepted this.
    #[test]
    fn keep_policy_validates_against_the_virtual_current_policy() {
        let attr = SchedAttrFields {
            policy: 99, // ignored under KEEP_POLICY, and deliberately invalid
            sched_flags: SCHED_FLAG_KEEP_POLICY,
            priority: 1,
            runtime: 0,
            deadline: 0,
            period: 0,
        };
        assert_eq!(
            validate_sched_attr_after_lookup(&attr),
            Err(Errno::EINVAL),
            "priority 1 under the virtual SCHED_OTHER current policy must be refused"
        );

        // The companion that must keep passing: the ignored policy field really
        // is ignored, so the same request at priority 0 is accepted.
        let ok = SchedAttrFields {
            priority: 0,
            ..attr
        };
        assert_eq!(
            validate_sched_attr_after_lookup(&ok),
            Ok(()),
            "KEEP_POLICY must still ignore the policy field itself"
        );
    }

    /// ITEM 3 COHERENCE: the substituted policy is the one the guest can
    /// actually observe, so the two sites cannot drift apart silently.
    #[test]
    fn the_virtual_current_policy_is_what_sched_getattr_reports() {
        assert_eq!(
            VIRTUAL_CURRENT_POLICY,
            libc::SCHED_OTHER as u32,
            "handle_sched_getattr writes SCHED_OTHER into sched_policy for every thread; \
             KEEP_POLICY must substitute that same value"
        );
    }
}

/// The real uid of thread `tid`, from `/proc/<tid>/status`.
pub(crate) fn real_uid(tid: i32) -> Option<u32> {
    let status = std::fs::read_to_string(format!("/proc/{tid}/status")).ok()?;
    status
        .lines()
        .find_map(|line| line.strip_prefix("Uid:"))?
        .split_whitespace()
        .next()?
        .parse()
        .ok()
}

/// The sizes of the three versions of `struct clone_args`
/// (`CLONE_ARGS_SIZE_VER0` to `_VER2`, include/uapi/linux/sched.h): the
/// smallest `clone3` accepts, the one with `set_tid`, and the one v6.16 reads.
const CLONE_ARGS_SIZE_VER0: usize = 64;
const CLONE_ARGS_SIZE_VER1: usize = 80;
const CLONE_ARGS_SIZE_VER2: usize = 88;

/// The most bytes of a `struct clone_args` [`inject_traced_clone3`] stages,
/// within the guest stack scratch's capacity.
const CLONE3_STAGED_MAX: usize = 512;

/// What [`inject_traced_clone`] did with a clone-family call.
enum CloneInjection {
    /// The call ran, with this result.
    Ran(Result<i64, Errno>),
    /// The call did not run: the reason it cannot be made traced.
    Refused(String),
}

/// Injects the guest's `clone_family` call with `CLONE_UNTRACED` cleared.
///
/// `CLONE_UNTRACED` keeps a tracer from attaching to the child
/// (`kernel_clone`, kernel/fork.c). No guest task has a tracer of its own:
/// Detcore answers every guest `ptrace` with `EPERM`
/// (`is_privileged_observation_refused_syscall`), and natively an untraced
/// program has none either, so for the guest the flag changes nothing. Under
/// a tracing backend every guest task must be traced: Detcore admits the
/// child to its scheduler as the clone returns and waits for it to take its
/// first turn, which an untraced child never does, so the run waited forever.
/// Cleared, the child is traced like every other and runs as it would
/// natively. A backend that does not trace children ignores the flag, so the
/// call is the same there. `flags` are the call's, as
/// [`Detcore::handle_clone_family`] read them.
async fn inject_traced_clone<T: RecordOrReplay, G: Guest<Detcore<T>>>(
    guest: &mut G,
    clone_family: syscalls::family::CloneFamily,
    flags: CloneFlags,
) -> CloneInjection {
    use syscalls::family::CloneFamily;
    if !flags.contains(CloneFlags::CLONE_UNTRACED) {
        return CloneInjection::Ran(
            crate::reserved_input::inject_original_clone(guest, Syscall::from(clone_family)).await,
        );
    }
    match clone_family {
        CloneFamily::Clone(clone) => {
            let traced = clone.with_flags(clone.flags() - nix::sched::CloneFlags::CLONE_UNTRACED);
            CloneInjection::Ran(
                crate::reserved_input::inject_original_clone(guest, Syscall::Clone(traced)).await,
            )
        }
        CloneFamily::Clone3(clone) => inject_traced_clone3(guest, clone).await,
        #[cfg(not(target_arch = "aarch64"))]
        CloneFamily::Fork(_) | CloneFamily::Vfork(_) => {
            unreachable!("fork and vfork take no flags")
        }
    }
}

/// [`inject_traced_clone`] of a `clone3` call, whose flags are in the guest's
/// `struct clone_args`. That struct is left as it is: a copy without
/// `CLONE_UNTRACED` is staged in the guest stack scratch, with the bytes under
/// it saved and put back after the call, as Detcore stages a pre-call lookup
/// buffer there. On ptrace that is below the red zone; a child that does not
/// share the caller's memory keeps the copy there, below its stack pointer,
/// where the ABI lets a signal frame write. Other backends lend an arena of
/// their own.
///
/// The copy holds every byte up to the guest's last nonzero one, and at
/// least those the kernel reads, so the kernel judges it as it would the
/// guest's struct (`copy_clone_args_from_user`, kernel/fork.c). A call the
/// kernel fails before reading the struct (no struct, one it cannot read, a
/// size it refuses) is injected as the guest made it and fails as natively.
/// Two calls are refused by name rather than run untraced: one whose nonzero
/// bytes do not fit the scratch, and one whose pointers lead into it.
async fn inject_traced_clone3<T: RecordOrReplay, G: Guest<Detcore<T>>>(
    guest: &mut G,
    clone: syscalls::Clone3,
) -> CloneInjection {
    let size = clone.size();
    let page = usize::try_from(unsafe { libc::sysconf(libc::_SC_PAGESIZE) }).unwrap_or(4096);
    let mut bytes = vec![0_u8; size];
    let readable = clone.args().is_some_and(|args| {
        (CLONE_ARGS_SIZE_VER0..=page).contains(&size)
            && crate::syscalls::read_guest_exact(&guest.memory(), args.cast(), &mut bytes).is_ok()
    });
    if !readable {
        return CloneInjection::Ran(
            crate::reserved_input::inject_original_clone(guest, Syscall::Clone3(clone)).await,
        );
    }
    let refused = |why: &str| {
        CloneInjection::Refused(format!(
            "clone3 with CLONE_UNTRACED: hermit must trace the child, so it clears the flag in a \
             copy of clone_args staged below the stack pointer, but {why}"
        ))
    };
    let nonzero = bytes
        .iter()
        .rposition(|byte| *byte != 0)
        .map_or(0, |last| last + 1);
    let len = nonzero.max(size.min(CLONE_ARGS_SIZE_VER2));
    if len > CLONE3_STAGED_MAX {
        return refused(&format!(
            "its nonzero bytes run past the {CLONE3_STAGED_MAX} that can be staged"
        ));
    }
    let mut copy = [0_u8; CLONE3_STAGED_MAX];
    copy[..len].copy_from_slice(&bytes[..len]);
    let field = |copy: &[u8], offset: usize| {
        u64::from_ne_bytes(copy[offset..offset + 8].try_into().unwrap())
    };
    let traced = field(&copy, 0) & !CloneFlags::CLONE_UNTRACED.bits();
    copy[..8].copy_from_slice(&traced.to_ne_bytes());

    // `GuestStack` starts its allocations 128 bytes below the stack pointer.
    let rsp = guest.regs().await.rsp as usize;
    let Some(start) = rsp.checked_sub(128 + CLONE3_STAGED_MAX) else {
        return refused("the stack pointer is too low to stage it");
    };
    let staged = start..start + CLONE3_STAGED_MAX;
    // What the kernel writes through the struct's pointers (pidfd, child_tid,
    // parent_tid) or reads through set_tid, which the restore below would
    // erase or the copy has already overwritten.
    let set_tid_bytes = if len >= CLONE_ARGS_SIZE_VER1 {
        field(&copy, 72).saturating_mul(4)
    } else {
        0
    };
    let pointed = [
        (field(&copy, 8), 4),
        (field(&copy, 16), 4),
        (field(&copy, 24), 4),
        (field(&copy, 64), set_tid_bytes),
    ];
    if pointed.iter().any(|&(address, bytes)| {
        let address = address as usize;
        bytes > 0 && address < staged.end && address.saturating_add(bytes as usize) > staged.start
    }) {
        return refused("one of its pointers leads into the staged copy");
    }

    let mut stack = guest.stack().await;
    let scratch: Addr<[u8; CLONE3_STAGED_MAX]> = stack.push(copy);
    let mut saved = [0_u8; CLONE3_STAGED_MAX];
    if let Err(errno) = crate::syscalls::read_guest_exact(
        &guest.memory(),
        AddrMut::from_raw(scratch.as_raw()).expect("a nonzero address"),
        &mut saved,
    ) {
        return refused(&format!("the stack below it cannot be read ({errno})"));
    }
    let guard = match stack.commit() {
        Ok(guard) => guard,
        Err(errno) => {
            restore_staged_clone_args(guest, scratch, &saved);
            return refused(&format!("the stack below it cannot be written ({errno})"));
        }
    };
    let result = crate::reserved_input::inject_original_clone(
        guest,
        Syscall::Clone3(
            clone
                .with_args(AddrMut::from_raw(scratch.as_raw()))
                .with_size(len),
        ),
    )
    .await;
    restore_staged_clone_args(guest, scratch, &saved);
    drop(guard);
    CloneInjection::Ran(result)
}

/// Puts back the guest bytes that [`inject_traced_clone3`] staged its copy
/// over.
fn restore_staged_clone_args<T: RecordOrReplay, G: Guest<Detcore<T>>>(
    guest: &mut G,
    scratch: Addr<[u8; CLONE3_STAGED_MAX]>,
    saved: &[u8; CLONE3_STAGED_MAX],
) {
    let restored = AddrMut::<u8>::from_raw(scratch.as_raw())
        .is_some_and(|scratch| guest.memory().write_exact(scratch, saved).is_ok());
    if !restored {
        info!("Could not restore the guest bytes under a staged clone_args.");
    }
}

/// The 8-byte field at `offset` of a clone3 call's `struct clone_args`,
/// which may be any size the kernel accepts from 64 bytes (its first
/// version) up: read alone, so that a shorter struct at the end of a mapping
/// is read as the kernel reads it. `None` for a size below 64, a field past
/// the size, or an unreadable field.
fn clone3_field<M: MemoryAccess>(
    memory: &M,
    clone: &syscalls::Clone3,
    offset: usize,
) -> Option<u64> {
    if clone.size() < CLONE_ARGS_SIZE_VER0 || offset + 8 > clone.size() {
        return None;
    }
    let field = clone.args()?.as_raw().checked_add(offset)?;
    // Past user memory there is nothing to read, and a read's address
    // arithmetic near the top of the address space would overflow.
    if !super::chosen_ids::within_user_memory(field, std::mem::size_of::<u64>()) {
        return None;
    }
    memory.read_value(Addr::<u64>::from_raw(field)?).ok()
}

/// Whether a `clone3`'s exit signal and the low byte of its flags pass the
/// kernel's checks: the exit signal is a signal number, and the flags hold
/// nothing in `CSIGNAL` but `CLONE_NEWTIME`, which `clone3` accepts from
/// Linux 6.3 (`clone3_args_valid`). On an older kernel, which refuses
/// `CLONE_NEWTIME` with EINVAL, a refusal after this is the conservative
/// side.
fn clone3_signal_fields_valid(flags: u64, exit_signal: u64) -> bool {
    const CSIGNAL: u64 = 0xff;
    const CLONE_NEWTIME: u64 = 0x80;
    exit_signal <= 64 && flags & CSIGNAL & !CLONE_NEWTIME == 0
}

#[cfg(test)]
mod clone3_signal_fields_tests {
    /// CLONE_NEWTIME is the one CSIGNAL bit clone3 accepts in its flags;
    /// every other one, or an exit signal above 64, is the kernel's EINVAL.
    #[test]
    fn clone3_accepts_only_clone_newtime_among_the_csignal_bits() {
        assert!(super::clone3_signal_fields_valid(0x80, 17));
        assert!(super::clone3_signal_fields_valid(0, 64));
        for bit in 0..7 {
            assert!(!super::clone3_signal_fields_valid(1 << bit, 17), "{bit}");
        }
        assert!(!super::clone3_signal_fields_valid(0, 65));
    }
}

/// Whether Linux refuses `clone_family` with EINVAL, from its flags and its
/// `struct clone_args` alone, before it reads anything else or creates
/// anything. A `clone3` is decided only where no check the kernel makes first
/// could fail another way: its struct, of a size the kernel takes, is read
/// whole with the guest's own access, as `copy_from_user` reads it, has no
/// nonzero tail past the fields known here (E2BIG), and names no `set_tid`
/// array, whose copy could fault (EFAULT). Linux's EINVALs that depend on the
/// caller's state, `CLONE_PARENT` from a namespace's init and a thread after
/// `unshare(CLONE_NEWPID)`, are left to the backend. `user_limit` is the
/// guest's user address limit, as its backend reports it
/// (`Guest::user_address_limit`), if it does.
fn linux_refuses_clone_flags<M: MemoryAccess>(
    memory: &M,
    clone_family: &syscalls::family::CloneFamily,
    user_limit: Option<u64>,
) -> bool {
    match clone_family {
        // `clone` takes the low 32 bits of its argument, less the exit signal
        // in the low byte, and writes a pidfd where it writes the parent's tid.
        syscalls::family::CloneFamily::Clone(clone) => {
            clone_flags_einval(u64::from(clone.flags().bits() as u32) & !0xff, true)
        }
        syscalls::family::CloneFamily::Clone3(clone) => {
            let size = clone.size();
            let page = usize::try_from(unsafe { libc::sysconf(libc::_SC_PAGESIZE) }).unwrap_or(0);
            let mut bytes = vec![0u8; size.min(page)];
            (CLONE_ARGS_SIZE_VER0..=page).contains(&size)
                && clone
                    .args()
                    .and_then(|args| Addr::<u8>::from_raw(args.as_raw()))
                    .filter(|args| super::chosen_ids::within_user_memory(args.as_raw(), size))
                    .is_some_and(|args| {
                        memory.read_exact_with_user_access(args, &mut bytes).is_ok()
                    })
                && clone3_args_einval(&bytes, user_limit)
        }
        #[cfg(not(target_arch = "aarch64"))]
        _ => false,
    }
}

/// Whether Linux refuses a clone with these `flags` with EINVAL, whatever the
/// caller's state: the check of `kernel_clone` for a pidfd written where the
/// parent's tid goes (`pidfd_is_parent_tid`), and the checks `copy_process`
/// makes first, at Linux v6.17:
/// https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/kernel/fork.c?h=v6.17#n2582
/// https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/kernel/fork.c?h=v6.17#n1935
fn clone_flags_einval(flags: u64, pidfd_is_parent_tid: bool) -> bool {
    let flags = CloneFlags::from_bits_retain(flags);
    let thread = flags.contains(CloneFlags::CLONE_THREAD);
    (flags.contains(CloneFlags::CLONE_PIDFD | CloneFlags::CLONE_PARENT_SETTID)
        && pidfd_is_parent_tid)
        || flags.contains(CloneFlags::CLONE_NEWNS | CloneFlags::CLONE_FS)
        || flags.contains(CloneFlags::CLONE_NEWUSER | CloneFlags::CLONE_FS)
        || (thread && !flags.contains(CloneFlags::CLONE_SIGHAND))
        || (flags.contains(CloneFlags::CLONE_SIGHAND) && !flags.contains(CloneFlags::CLONE_VM))
        || (thread && flags.intersects(CloneFlags::CLONE_NEWUSER | CloneFlags::CLONE_NEWPID))
        || flags.contains(CloneFlags::CLONE_PIDFD | CloneFlags::CLONE_DETACHED)
}

/// Whether Linux refuses a `clone3` whose `struct clone_args` is `bytes` with
/// EINVAL before it creates anything: the checks of
/// `copy_clone_args_from_user` and `clone3_args_valid`, then
/// [`clone_flags_einval`]. False wherever another error could come first, a
/// nonzero tail (E2BIG) or a `set_tid` copy (EFAULT):
/// https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/kernel/fork.c?h=v6.17#n2768
/// https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/kernel/fork.c?h=v6.17#n2849
///
/// `clone3_stack_valid` refuses a stack range that `access_ok` refuses,
/// one whose end passes the user address limit (`__access_ok` and
/// `valid_user_address`, arch/x86/include/asm/uaccess_64.h:56-57 and 98-107
/// at v6.17). That limit is the kernel's (four- or five-level paging on a
/// host), so it is decided only from `user_limit`, the guest's limit as its
/// backend reports it, and left to the backend without one:
/// https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/kernel/fork.c?h=v6.17#n2829
fn clone3_args_einval(bytes: &[u8], user_limit: Option<u64>) -> bool {
    const CLONE_CLEAR_SIGHAND: u64 = 1 << 32;
    const CLONE_INTO_CGROUP: u64 = 1 << 33;
    if bytes
        .iter()
        .skip(CLONE_ARGS_SIZE_VER2)
        .any(|byte| *byte != 0)
    {
        return false;
    }
    let field = |offset: usize| {
        let mut word = [0u8; 8];
        for (i, byte) in word.iter_mut().enumerate() {
            *byte = bytes.get(offset + i).copied().unwrap_or(0);
        }
        u64::from_ne_bytes(word)
    };
    let (flags, exit_signal, stack, stack_size) = (field(0), field(32), field(40), field(48));
    let (set_tid, set_tid_size) = (field(64), field(72));
    let into_cgroup = flags & CLONE_INTO_CGROUP != 0;
    if set_tid_size > 32
        || (set_tid == 0) != (set_tid_size == 0)
        || exit_signal > 64
        || (into_cgroup && (field(80) > i32::MAX as u64 || bytes.len() < CLONE_ARGS_SIZE_VER2))
    {
        return true;
    }
    if set_tid != 0 {
        return false;
    }
    let sighand = libc::CLONE_SIGHAND as u64 | CLONE_CLEAR_SIGHAND;
    flags & !(0xffff_ffff | CLONE_CLEAR_SIGHAND | CLONE_INTO_CGROUP) != 0
        || !clone3_signal_fields_valid(flags, exit_signal)
        || flags & libc::CLONE_DETACHED as u64 != 0
        || flags & sighand == sighand
        || (flags & (libc::CLONE_THREAD | libc::CLONE_PARENT) as u64 != 0 && exit_signal != 0)
        || (stack == 0) != (stack_size == 0)
        || stack.checked_add(stack_size).is_none()
        || (stack != 0 && user_limit.is_some_and(|limit| stack + stack_size > limit))
        || clone_flags_einval(flags, field(8) == field(24))
}

#[cfg(test)]
mod linux_clone_einval_tests {
    use super::clone_flags_einval;
    use super::clone3_args_einval;

    const VM: u64 = libc::CLONE_VM as u64;
    const FS: u64 = libc::CLONE_FS as u64;
    const FILES: u64 = libc::CLONE_FILES as u64;
    const SIGHAND: u64 = libc::CLONE_SIGHAND as u64;
    const THREAD: u64 = libc::CLONE_THREAD as u64;
    const PIDFD: u64 = 0x1000;
    const PARENT_SETTID: u64 = libc::CLONE_PARENT_SETTID as u64;
    /// glibc's pthread_create flags, less the tid and TLS flags.
    const PTHREAD: u64 = VM | FS | FILES | SIGHAND | THREAD | libc::CLONE_SYSVSEM as u64;

    /// Exactly copy_process's first checks and kernel_clone's pidfd check
    /// refuse: never the sharing Linux allows, such as a process with
    /// CLONE_VM and CLONE_FS, CLONE_FILES or CLONE_SIGHAND, or a thread
    /// without CLONE_FS, CLONE_FILES or CLONE_SYSVSEM.
    #[test]
    fn only_the_kernels_flag_rules_refuse() {
        let newns = libc::CLONE_NEWNS as u64;
        let newuser = libc::CLONE_NEWUSER as u64;
        let newpid = libc::CLONE_NEWPID as u64;
        let detached = libc::CLONE_DETACHED as u64;
        for (flags, pidfd_is_parent_tid, einval) in [
            (0, true, false),
            (VM | libc::CLONE_VFORK as u64, true, false),
            (PTHREAD, true, false),
            (VM | SIGHAND | THREAD, true, false),
            (VM | FS, true, false),
            (VM | FILES, true, false),
            (VM | SIGHAND, true, false),
            (VM | SIGHAND | THREAD | newns, true, false),
            (PIDFD | PTHREAD, true, false),
            (PIDFD | PARENT_SETTID, false, false),
            (newns | FS, true, true),
            (newuser | FS, true, true),
            (VM | FS | FILES | THREAD, true, true),
            (SIGHAND, true, true),
            (PTHREAD | newpid, true, true),
            (VM | SIGHAND | THREAD | newuser, true, true),
            (PIDFD | PARENT_SETTID, true, true),
            (PIDFD | detached, true, true),
        ] {
            assert_eq!(
                clone_flags_einval(flags, pidfd_is_parent_tid),
                einval,
                "{flags:#x} {pidfd_is_parent_tid}"
            );
        }
    }

    /// A clone_args of `len` bytes with these fields, the rest zero.
    fn args(len: usize, fields: &[(usize, u64)]) -> Vec<u8> {
        let mut bytes = vec![0u8; len];
        for (offset, value) in fields {
            bytes[*offset..*offset + 8].copy_from_slice(&value.to_ne_bytes());
        }
        bytes
    }

    /// clone3's own checks refuse first, in their order: a set_tid shape,
    /// the exit signal, CLONE_INTO_CGROUP's field, then flags clone3 does not
    /// take, CLONE_SIGHAND with CLONE_CLEAR_SIGHAND, an exit signal for a
    /// thread and an unpaired or overflowing stack. Where the kernel could
    /// fail another way first, a nonzero tail (E2BIG) or a set_tid array to
    /// copy (EFAULT), nothing is decided.
    #[test]
    fn clone3_decides_only_what_the_kernel_checks_first() {
        let sigchld = libc::SIGCHLD as u64;
        let fork = [(32, sigchld)];
        for (bytes, einval) in [
            (args(64, &fork), false),
            (args(88, &[(0, PTHREAD), (40, 0x1000), (48, 0x1000)]), false),
            (args(88, &[(0, 0x80), (32, sigchld)]), false),
            (args(128, &[(0, VM | FS), (32, sigchld)]), false),
            (args(88, &[(0, PTHREAD), (32, sigchld)]), true),
            (
                args(88, &[(0, libc::CLONE_PARENT as u64), (32, sigchld)]),
                true,
            ),
            (args(88, &[(0, 0x11)]), true),
            (args(88, &[(0, libc::CLONE_DETACHED as u64)]), true),
            (args(88, &[(0, VM | SIGHAND | (1 << 32))]), true),
            (args(88, &[(0, 1 << 34)]), true),
            (args(88, &[(32, 65)]), true),
            (args(88, &[(40, 0x1000)]), true),
            (args(88, &[(48, 0x1000)]), true),
            (args(88, &[(40, u64::MAX), (48, 2)]), true),
            (args(88, &[(64, 0x1000)]), true),
            (args(88, &[(72, 1)]), true),
            (args(88, &[(64, 0x1000), (72, 33)]), true),
            (args(80, &[(0, 1 << 33)]), true),
            (args(88, &[(0, 1 << 33), (80, 1 << 31)]), true),
            (args(88, &[(0, 1 << 33), (80, 3)]), false),
            (args(88, &[(0, THREAD), (64, 0x1000), (72, 1)]), false),
            (args(96, &[(0, THREAD), (88, 1)]), false),
            (args(96, &[(0, THREAD)]), true),
            (
                args(88, &[(0, PIDFD | PARENT_SETTID), (8, 8), (24, 8)]),
                true,
            ),
            (
                args(88, &[(0, PIDFD | PARENT_SETTID), (8, 8), (24, 16)]),
                false,
            ),
            (
                args(64, &[(0, libc::CLONE_NEWNS as u64 | FS), (32, sigchld)]),
                true,
            ),
        ] {
            assert_eq!(clone3_args_einval(&bytes, None), einval, "{bytes:x?}");
        }
    }

    /// A stack whose end passes the user address limit the backend reports
    /// is refused, as `access_ok` refuses it: one in the kernel's half, and
    /// one a byte past the limit. One that ends at the limit is not, and
    /// without a reported limit nothing is decided from the stack's place.
    #[test]
    fn clone3_refuses_a_stack_past_the_reported_user_limit() {
        let sigchld = libc::SIGCHLD as u64;
        let limit = (1_u64 << 47) - 4096;
        let stack = |base: u64, size: u64| args(88, &[(32, sigchld), (40, base), (48, size)]);
        for (bytes, user_limit, einval) in [
            (stack(0xffff_8000_0000_0000, 0x1000), Some(limit), true),
            (stack(0xffff_8000_0000_0000, 0x1000), None, false),
            (stack(limit - 0x1000, 0x1001), Some(limit), true),
            (stack(limit - 0x1000, 0x1000), Some(limit), false),
            (stack(0x7000_0000, 0x1000), Some(limit), false),
            (args(88, &[(32, sigchld)]), Some(limit), false),
        ] {
            assert_eq!(
                clone3_args_einval(&bytes, user_limit),
                einval,
                "{bytes:x?} {user_limit:?}"
            );
        }
    }
}

/// Where a `CLONE_PIDFD` clone writes the new process's pidfd (`clone`'s
/// `parent_tid` argument, or `clone3`'s `pidfd` field), for a child Detcore
/// tracks the pidfd of (`Detcore::register_clone_pidfd`): one that shares
/// neither the caller's memory nor its descriptor table and is no vfork
/// child. Such a child could rewrite the word, or close or replace the
/// descriptor, before the caller tracks it, and a vfork parent resumes, and
/// tracks it, only after its child is done, while a sibling may already
/// use the pidfd; Detcore leaves those pidfds untracked, as before
/// https://github.com/rrnewton/hermit/issues/4430
/// (https://github.com/rrnewton/hermit/issues/4443).
fn clone_pidfd_address<M: MemoryAccess>(
    clone_family: &syscalls::family::CloneFamily,
    memory: &M,
    flags: CloneFlags,
) -> Option<usize> {
    let (flags, address) = match clone_family {
        syscalls::family::CloneFamily::Clone(clone) => {
            (flags, clone.ptid().map(|ptid| ptid.as_raw()))
        }
        syscalls::family::CloneFamily::Clone3(clone) => (
            flags,
            Some(usize::try_from(clone3_field(memory, clone, 8)?).ok()?),
        ),
        #[cfg(not(target_arch = "aarch64"))]
        _ => return None,
    };
    if !flags.contains(CloneFlags::CLONE_PIDFD)
        || flags
            .intersects(CloneFlags::CLONE_VM | CloneFlags::CLONE_FILES | CloneFlags::CLONE_VFORK)
    {
        return None;
    }
    address
}

/// A5 step 3c.1e B (<https://github.com/rrnewton/hermit/issues/4485>): a
/// managed child wait under the in-guest delivery gate reads the guest's mask
/// without replacing it and restores nothing, so the mask its requests publish
/// while it parks, and the one the guest resumes under, is the guest's own,
/// never "every signal blocked".
#[cfg(test)]
mod disposition_mask_tests {
    use std::sync::Mutex;

    use reverie::Errno;
    use reverie::Error;
    use reverie::GlobalRPC;
    use reverie::GlobalTool;
    use reverie::Guest;
    use reverie::Pid;
    use reverie::syscalls::Addr;
    use reverie::syscalls::AddrMut;
    use reverie::syscalls::LocalMemory;
    use reverie::syscalls::MemoryAccess;
    use reverie::syscalls::SyscallInfo;

    use super::*;
    use crate::tool_global::GlobalState;

    const GUEST_MASK: KernelSigset = (1 << (libc::SIGUSR1 - 1)) | (1 << (libc::SIGHUP - 1));

    struct UnusedStack;
    struct UnusedStackGuard;
    impl Drop for UnusedStackGuard {
        fn drop(&mut self) {}
    }
    impl reverie::Stack for UnusedStack {
        type StackGuard = UnusedStackGuard;
        fn size(&self) -> usize {
            panic!("the disposition mask uses the caller's addresses")
        }
        fn capacity(&self) -> usize {
            panic!("the disposition mask uses the caller's addresses")
        }
        fn push<'a, V>(&mut self, _: V) -> Addr<'a, V> {
            panic!("the disposition mask uses the caller's addresses")
        }
        fn reserve<'a, V>(&mut self) -> AddrMut<'a, V> {
            panic!("the disposition mask uses the caller's addresses")
        }
        fn commit(self) -> Result<Self::StackGuard, Errno> {
            panic!("the disposition mask uses the caller's addresses")
        }
    }

    /// A thread whose backend answers each injected `rt_sigprocmask` as the
    /// kernel would for a thread whose mask is `mask`, and records the
    /// `(how, set given)` of each.
    struct MaskGuest {
        config: Config,
        thread: crate::ThreadState<()>,
        mask: KernelSigset,
        calls: Mutex<Vec<(i32, bool)>>,
    }

    #[reverie::tool]
    impl GlobalRPC<GlobalState> for MaskGuest {
        async fn send_rpc(
            &self,
            message: <GlobalState as GlobalTool>::Request,
        ) -> <GlobalState as GlobalTool>::Response {
            panic!("the disposition mask sends no RPC here: {:?}", message.2)
        }
        fn config(&self) -> &Config {
            &self.config
        }
    }

    #[reverie::tool]
    impl Guest<Detcore> for MaskGuest {
        type Memory = LocalMemory;
        type Stack = UnusedStack;
        fn tid(&self) -> Pid {
            Pid::from_raw(41)
        }
        fn pid(&self) -> Pid {
            Pid::from_raw(41)
        }
        fn ppid(&self) -> Option<Pid> {
            None
        }
        fn memory(&self) -> LocalMemory {
            LocalMemory::new()
        }
        fn thread_state(&self) -> &crate::ThreadState<()> {
            &self.thread
        }
        fn thread_state_mut(&mut self) -> &mut crate::ThreadState<()> {
            &mut self.thread
        }
        async fn regs(&mut self) -> libc::user_regs_struct {
            panic!("no registers are read")
        }
        async fn stack(&mut self) -> UnusedStack {
            panic!("the disposition mask uses the caller's addresses")
        }
        async fn daemonize(&mut self) {
            panic!("no daemonize")
        }
        async fn inject<S: SyscallInfo>(&mut self, call: S) -> Result<i64, Errno> {
            assert_eq!(call.number(), syscalls::Sysno::rt_sigprocmask);
            let args = call.into_parts().1;
            let (how, set, old) = (args.arg0 as i32, args.arg1, args.arg2);
            self.calls.lock().unwrap().push((how, set != 0));
            let previous = self.mask;
            if set != 0 {
                let set: KernelSigset = LocalMemory::new()
                    .read_value(Addr::<KernelSigset>::from_raw(set).unwrap())
                    .unwrap();
                self.mask = set;
            }
            if old != 0 {
                LocalMemory::new()
                    .write_value(AddrMut::<KernelSigset>::from_raw(old).unwrap(), &previous)
                    .unwrap();
            }
            Ok(0)
        }
        async fn tail_inject<S: SyscallInfo>(&mut self, _: S) -> reverie::Never {
            panic!("no tail injection")
        }
        fn set_timer(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
            panic!("no timer")
        }
        fn set_timer_precise(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
            panic!("no timer")
        }
        fn read_clock(&mut self) -> Result<u64, Error> {
            panic!("no clock")
        }
    }

    fn mask_guest(gate: bool) -> MaskGuest {
        let mut config = Config {
            sequentialize_threads: true,
            max_timeslice: None,
            in_guest_signal_delivery: gate,
            ..Config::default()
        };
        config.backend = reverie::BackendCapabilities::LITEINST_IN_GUEST;
        let detpid = DetPid::from_raw(41);
        let mut thread = crate::ThreadState::new(detpid, &config, ());
        thread.detpid = Some(detpid);
        MaskGuest {
            config,
            thread,
            mask: GUEST_MASK,
            calls: Mutex::new(Vec::new()),
        }
    }

    /// Under the gate the wait's mask step is a query and its restore is
    /// nothing, so the guest's mask stays its own throughout; with the gate
    /// off the in-guest backend keeps today's block and restore. Mutation:
    /// "the block left in place under the gate" (the gated row's mask is the
    /// blocked set while the wait runs, and its calls show a set).
    #[tokio::test]
    async fn a_gated_managed_wait_reads_the_guest_mask_without_replacing_it() {
        for (gate, calls_during, mask_during, calls_after) in [
            (
                true,
                vec![(libc::SIG_SETMASK, false)],
                GUEST_MASK,
                vec![(libc::SIG_SETMASK, false)],
            ),
            (
                false,
                vec![(libc::SIG_SETMASK, true)],
                blocked_signal_mask(),
                vec![(libc::SIG_SETMASK, true), (libc::SIG_SETMASK, true)],
            ),
        ] {
            let mut guest = mask_guest(gate);
            let blocked = blocked_signal_mask();
            let mut old = 0 as KernelSigset;
            let blocked_addr =
                Addr::<KernelSigset>::from_raw(&blocked as *const _ as usize).unwrap();
            let old_addr = AddrMut::<KernelSigset>::from_raw(&mut old as *mut _ as usize).unwrap();
            let read = block_signals_for_disposition(&mut guest, blocked_addr, old_addr)
                .await
                .unwrap();
            assert_eq!(read, GUEST_MASK, "gate={gate}");
            assert_eq!(*guest.calls.lock().unwrap(), calls_during, "gate={gate}");
            assert_eq!(
                guest.mask, mask_during,
                "gate={gate}: the mask while the wait runs"
            );
            restore_signals_after_disposition(&mut guest, old_addr)
                .await
                .unwrap();
            assert_eq!(*guest.calls.lock().unwrap(), calls_after, "gate={gate}");
            assert_eq!(
                guest.mask, GUEST_MASK,
                "gate={gate}: the mask after the wait"
            );
        }
    }
}