Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript
142 KB
Raw Blame
//! Windows launch encoding and the native owned, channel-present process adapter.
//! Explicit transfer, suspended Job assignment and verification precede child execution.
//! The daemon lifecycle in daemon.rs drives these adapters, including owner-exit retirement.

use std::io;

const DESCRIPTOR_COUNT: usize = 4;
const FOPEN: u8 = 1;
const FPIPE: u8 = 8;
const FDEV: u8 = 64;

/// CRT/libuv lpReserved2: native int count, count flag bytes, then packed native HANDLEs.
/// Handles are copied as bytes: the handle region is not necessarily aligned on 64-bit Windows.
/// The caller must retain this buffer until CreateProcessW returns; cbReserved2 is its u16 length.
/// Entries 0..2 are inherited NUL stdin and file-backed stdout/stderr; entry 3 is the
/// dedicated connected duplex pipe. Do not reuse this for pipe-backed standard streams.
/// This buffer does NOT constrain inheritance: an explicit STARTUPINFOEX handle list is required.
pub(super) fn fd3_bootstrap(handles: [usize; DESCRIPTOR_COUNT]) -> io::Result<Vec<u8>> {
    packed_bootstrap(&[FOPEN | FDEV, FOPEN, FOPEN, FOPEN | FPIPE], &handles)
}

fn packed_bootstrap(flags: &[u8], handles: &[usize]) -> io::Result<Vec<u8>> {
    let invalid = || io::Error::new(io::ErrorKind::InvalidInput, "invalid descriptor bootstrap size");
    if flags.len() != handles.len() {
        return Err(invalid());
    }
    let count = i32::try_from(handles.len()).map_err(|_| invalid())?;
    let size = handles.len().checked_mul(std::mem::size_of::<usize>())
        .and_then(|n| n.checked_add(flags.len()))
        .and_then(|n| n.checked_add(std::mem::size_of::<i32>()))
        .ok_or_else(invalid)?;
    u16::try_from(size).map_err(|_| invalid())?;
    let mut bytes = Vec::with_capacity(size);
    bytes.extend_from_slice(&count.to_ne_bytes());
    bytes.extend_from_slice(flags);
    for handle in handles {
        bytes.extend_from_slice(&handle.to_ne_bytes());
    }
    Ok(bytes)
}

/// Always quote each argument using Windows CRT escaping, including empty arguments.
/// Reject embedded NUL rather than letting CreateProcessW silently truncate a command line.
/// The executable must also be passed separately as lpApplicationName, never shell-interpreted.
pub(super) fn command_line(program: &str, args: &[String]) -> io::Result<Vec<u16>> {
    let mut line = String::new();
    for arg in std::iter::once(program).chain(args.iter().map(String::as_str)) {
        if arg.contains('\0') {
            return Err(io::Error::new(io::ErrorKind::InvalidInput, "NUL in launch argument"));
        }
        if !line.is_empty() {
            line.push(' ');
        }
        line.push('"');
        let mut slashes = 0;
        for ch in arg.chars() {
            if ch == '\\' {
                slashes += 1;
                continue;
            }
            let copies = if ch == '"' { slashes * 2 + 1 } else { slashes };
            line.extend(std::iter::repeat('\\').take(copies));
            slashes = 0;
            line.push(ch);
        }
        line.extend(std::iter::repeat('\\').take(slashes * 2));
        line.push('"');
    }
    let mut wide: Vec<u16> = line.encode_utf16().collect();
    // CreateProcessW's limit includes the terminating NUL.
    if wide.len() >= 32_767 {
        return Err(io::Error::new(io::ErrorKind::InvalidInput, "launch command line too long"));
    }
    wide.push(0);
    Ok(wide)
}

#[cfg(windows)]
pub(super) use native::{acquire_recovered_launch, ensure_record_directory, open_private_log, retire_if_owner_exited, spawn, RecoveredLaunch, SpawnFailure, WindowsChild};

#[cfg(windows)]
mod native {
    use super::{command_line, fd3_bootstrap};
    use super::super::{ChildEndpoint, ChildProcess, LaunchSpec};
    use std::ffi::OsString;
    use std::fs::File;
    use std::io;
    use std::os::windows::ffi::OsStrExt;
    use std::os::windows::io::{AsRawHandle, FromRawHandle, OwnedHandle};
    use std::os::windows::process::ExitStatusExt;
    use std::path::{Path, PathBuf};
    use std::process::ExitStatus;
    use std::ptr::{null, null_mut};
    use std::time::{Duration, Instant};
    use windows_sys::Win32::Foundation::*;
    use windows_sys::Win32::Globalization::CompareStringOrdinal;
    use windows_sys::Win32::Security::Authorization::*;
    use windows_sys::Win32::Security::*;
    use windows_sys::Win32::Storage::FileSystem::*;
    use windows_sys::Win32::System::Diagnostics::ToolHelp::{
        CreateToolhelp32Snapshot, Process32FirstW, Process32NextW, PROCESSENTRY32W, TH32CS_SNAPPROCESS,
    };
    use windows_sys::Win32::System::IO::*;
    use windows_sys::Win32::System::JobObjects::*;
    use windows_sys::Win32::System::Pipes::*;
    use windows_sys::Win32::System::Threading::*;

    // SDK winnt.h definitions, scoped here because the enabled windows-sys
    // namespaces do not expose them: ACE_HEADER.AceType and SID count are BYTEs.
    const ACCESS_ALLOWED_ACE_TYPE: u8 = 0x00;
    const SID_MAX_SUB_AUTHORITIES: u8 = 15;
    // GetDriveTypeW's documented UINT return constant: DRIVE_FIXED = 3.
    const DRIVE_FIXED: u32 = 3;

    // Redirected stdio does not prevent Windows from allocating a console for Node.
    const DAEMON_CREATION_FLAGS: u32 =
        CREATE_NO_WINDOW | CREATE_SUSPENDED | CREATE_UNICODE_ENVIRONMENT | EXTENDED_STARTUPINFO_PRESENT;

    const CLEANUP_WAIT: Duration = Duration::from_secs(2);
    fn owned(handle: HANDLE) -> io::Result<OwnedHandle> {
        if handle.is_null() || handle == INVALID_HANDLE_VALUE { return Err(io::Error::last_os_error()); }
        // SAFETY: a fresh native handle with exactly one owner.
        Ok(unsafe { OwnedHandle::from_raw_handle(handle) })
    }
    fn checked(ok: i32) -> io::Result<()> {
        if ok == 0 { Err(io::Error::last_os_error()) } else { Ok(()) }
    }
    fn wide(text: &std::ffi::OsStr) -> io::Result<Vec<u16>> {
        let mut value: Vec<u16> = text.encode_wide().collect();
        if value.contains(&0) { return Err(io::Error::new(io::ErrorKind::InvalidInput, "NUL in launch value")); }
        value.push(0);
        Ok(value)
    }
    fn duplicate(handle: HANDLE) -> io::Result<OwnedHandle> {
        let mut copy = null_mut();
        // SAFETY: duplicate only a caller-owned handle, within this process. The copy, not
        // the source, is inheritable and will appear in the exact startup transfer list.
        unsafe {
            checked(DuplicateHandle(GetCurrentProcess(), handle, GetCurrentProcess(), &mut copy,
                0, 1, DUPLICATE_SAME_ACCESS))?;
        }
        owned(copy)
    }

    struct Transfers { nul: OwnedHandle, stdout: OwnedHandle, stderr: OwnedHandle, channel: OwnedHandle }
    impl Transfers {
        fn new(log: &File, channel: &ChildEndpoint) -> io::Result<Self> {
            let name = wide(std::ffi::OsStr::new("NUL"))?;
            let nul = owned(unsafe { CreateFileW(name.as_ptr(), GENERIC_READ,
                FILE_SHARE_READ | FILE_SHARE_WRITE, null(), OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, null_mut()) })?;
            Ok(Self { nul: duplicate(nul.as_raw_handle())?, stdout: duplicate(log.as_raw_handle())?,
                stderr: duplicate(log.as_raw_handle())?, channel: duplicate(channel.as_raw_handle())? })
        }
        fn handles(&self) -> [HANDLE; 4] {
            [self.nul.as_raw_handle(), self.stdout.as_raw_handle(), self.stderr.as_raw_handle(), self.channel.as_raw_handle()]
        }
        fn bootstrap(&self) -> io::Result<Vec<u8>> {
            fd3_bootstrap(self.handles().map(|handle| handle as usize))
        }
    }
    struct Attributes { storage: Vec<usize>, initialized: bool }
    impl Attributes {
        fn new(handles: &mut [HANDLE; 4]) -> io::Result<Self> {
            let mut bytes = 0;
            // SAFETY: size-only query, as required by the attribute-list API.
            let queried = unsafe { InitializeProcThreadAttributeList(null_mut(), 1, 0, &mut bytes) };
            let query_error = io::Error::last_os_error();
            if queried != 0 || bytes == 0 || query_error.raw_os_error() != Some(ERROR_INSUFFICIENT_BUFFER as i32) {
                return Err(io::Error::other("startup attribute size query failed"));
            }
            let mut this = Self { storage: vec![0; bytes.div_ceil(std::mem::size_of::<usize>())], initialized: false };
            // SAFETY: aligned storage of queried size; handles stay stable through CreateProcessW.
            unsafe {
                checked(InitializeProcThreadAttributeList(this.pointer(), 1, 0, &mut bytes))?;
                this.initialized = true;
                checked(UpdateProcThreadAttribute(this.pointer(), 0, PROC_THREAD_ATTRIBUTE_HANDLE_LIST as usize,
                    handles.as_mut_ptr().cast(), std::mem::size_of_val(handles), null_mut(), null_mut()))?;
            }
            Ok(this)
        }
        fn pointer(&mut self) -> LPPROC_THREAD_ATTRIBUTE_LIST { self.storage.as_mut_ptr().cast() }
    }
    impl Drop for Attributes {
        fn drop(&mut self) {
            if self.initialized { unsafe { DeleteProcThreadAttributeList(self.pointer()) }; }
        }
    }

    fn compare_names(left: &[u16], right: &[u16]) -> io::Result<std::cmp::Ordering> {
        let left_len = i32::try_from(left.len()).map_err(io::Error::other)?;
        let right_len = i32::try_from(right.len()).map_err(io::Error::other)?;
        // SAFETY: length-delimited UTF-16 buffers; Windows ordinal case-insensitive ordering.
        match unsafe { CompareStringOrdinal(left.as_ptr(), left_len, right.as_ptr(), right_len, 1) } {
            1 => Ok(std::cmp::Ordering::Less), 2 => Ok(std::cmp::Ordering::Equal),
            3 => Ok(std::cmp::Ordering::Greater), _ => Err(io::Error::last_os_error()),
        }
    }
    fn environment(spec: &LaunchSpec) -> io::Result<Vec<u16>> {
        let mut entries: Vec<(Vec<u16>, Vec<u16>)> = std::env::vars_os()
            .map(|(key, value)| (key.encode_wide().collect(), value.encode_wide().collect())).collect();
        for (key, value) in &spec.envs {
            if key.is_empty() || key.contains('=') || key.contains('\0') || value.contains('\0') {
                return Err(io::Error::new(io::ErrorKind::InvalidInput, "invalid launch environment"));
            }
            let key: Vec<u16> = key.encode_utf16().collect();
            let value: Vec<u16> = value.encode_utf16().collect();
            let mut found = None;
            for (index, (existing, _)) in entries.iter().enumerate() {
                if compare_names(existing, &key)? == std::cmp::Ordering::Equal { found = Some(index); break; }
            }
            if let Some(index) = found { entries[index] = (key, value); } else { entries.push((key, value)); }
        }
        // Fallible insertion sort keeps an API failure observable instead of inventing an order.
        for index in 1..entries.len() {
            let mut at = index;
            while at > 0 && compare_names(&entries[at - 1].0, &entries[at].0)? == std::cmp::Ordering::Greater {
                entries.swap(at - 1, at); at -= 1;
            }
        }
        let mut block = Vec::new();
        for (key, value) in entries {
            block.extend(key); block.push(b'=' as u16); block.extend(value); block.push(0);
        }
        if block.is_empty() { block.push(0); }
        block.push(0);
        Ok(block)
    }
    fn application(spec: &LaunchSpec) -> io::Result<Vec<u16>> {
        let program = Path::new(&spec.program);
        let path = if program.components().count() > 1 || program.is_absolute() {
            program.to_path_buf()
        } else {
            let path = spec.envs.iter().rev().find(|(key, _)| key.eq_ignore_ascii_case("PATH"))
                .map(|(_, value)| OsString::from(value)).or_else(|| std::env::var_os("PATH"));
            let file = if program.extension().is_some() { program.to_path_buf() } else { program.with_extension("exe") };
            // Only absolute PATH entries: an empty or relative entry would resolve against the
            // current directory and could select a planted executable.
            path.as_deref().into_iter().flat_map(std::env::split_paths).filter(|dir| dir.is_absolute())
                .map(|dir| dir.join(&file))
                .find(|candidate| candidate.is_file())
                .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "daemon executable not found in launch PATH"))?
        };
        // Windows absolute() also resolves drive-relative paths; cwd itself is unchanged.
        let absolute = std::path::absolute(path)?;
        wide(absolute.as_os_str())
    }

    fn new_job() -> io::Result<OwnedHandle> {
        let job = owned(unsafe { CreateJobObjectW(null(), null()) })?;
        let mut limits: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = unsafe { std::mem::zeroed() };
        limits.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
        unsafe {
            checked(SetInformationJobObject(job.as_raw_handle(), JobObjectExtendedLimitInformation,
                (&limits as *const JOBOBJECT_EXTENDED_LIMIT_INFORMATION).cast(), std::mem::size_of_val(&limits) as u32))?;
            let mut observed: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = std::mem::zeroed();
            checked(QueryInformationJobObject(job.as_raw_handle(), JobObjectExtendedLimitInformation,
                (&mut observed as *mut JOBOBJECT_EXTENDED_LIMIT_INFORMATION).cast(), std::mem::size_of_val(&observed) as u32, null_mut()))?;
            if observed.BasicLimitInformation.LimitFlags != JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE {
                return Err(io::Error::other("owned Job limits not established"));
            }
        }
        Ok(job)
    }
    fn job_active(job: &OwnedHandle) -> io::Result<u32> {
        let mut accounting: JOBOBJECT_BASIC_ACCOUNTING_INFORMATION = unsafe { std::mem::zeroed() };
        unsafe {
            checked(QueryInformationJobObject(job.as_raw_handle(), JobObjectBasicAccountingInformation,
                (&mut accounting as *mut JOBOBJECT_BASIC_ACCOUNTING_INFORMATION).cast(), std::mem::size_of_val(&accounting) as u32, null_mut()))?;
        }
        Ok(accounting.ActiveProcesses)
    }

    #[cfg(test)]
    #[derive(Default, Debug)]
    struct Faults { assignment: bool, verification: bool, terminate: bool, wait: bool, query: bool }
    pub(crate) struct WindowsChild {
        process: OwnedHandle,
        thread: Option<OwnedHandle>,
        job: OwnedHandle,
        pid: u32,
        assigned: bool,
        failed: bool,
        // Set once the daemon resumed. An established launch whose status later turns
        // uncertain is retained as failed (no replacement, no health) but still stops
        // through the authenticated, channel-open path, never as a failed startup.
        established: bool,
        record: Option<OwnedRecord>,
        // Reuse the authenticated client with a duplicate of the created process
        // handle, never a fresh PID lookup. Keep pending I/O installed on errors.
        stop: Option<RecoveredLaunch>,
        stopping: bool,
        force_requested: bool,
        // Completion survives record/channel-close failures and checked retries.
        completed: bool,
        #[cfg(test)]
        faults: Faults,
    }
    impl std::fmt::Debug for WindowsChild {
        fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            formatter.debug_struct("WindowsChild").field("pid", &self.pid)
                .field("assigned", &self.assigned).field("failed", &self.failed).finish_non_exhaustive()
        }
    }
    impl WindowsChild {
        pub(crate) fn reject_launch(&mut self) { self.failed = true; }
        fn status(&self) -> io::Result<Option<ExitStatus>> {
            match unsafe { WaitForSingleObject(self.process.as_raw_handle(), 0) } {
                WAIT_TIMEOUT => Ok(None),
                WAIT_OBJECT_0 => {
                    let mut code = 0;
                    unsafe { checked(GetExitCodeProcess(self.process.as_raw_handle(), &mut code))?; }
                    Ok(Some(ExitStatus::from_raw(code)))
                }
                _ => Err(io::Error::last_os_error()),
            }
        }
        fn query(&self) -> io::Result<u32> {
            #[cfg(test)]
            if self.faults.query { return Err(io::Error::other("injected job query failure")); }
            job_active(&self.job)
        }
        fn terminate(&self) -> io::Result<()> {
            #[cfg(test)]
            if self.faults.terminate { return Err(io::Error::other("injected terminate failure")); }
            // Never PID-based: before assignment only the exact created process; afterward
            // only the anonymous retained Job. A nested-Job assignment error has no fallback.
            unsafe {
                checked(if self.assigned { TerminateJobObject(self.job.as_raw_handle(), 1) }
                    else { TerminateProcess(self.process.as_raw_handle(), 1) })
            }
        }
        fn complete(&mut self, grace: Duration) -> io::Result<()> {
            let deadline = Instant::now() + grace;
            let mut errors = Vec::new();
            loop {
                match self.status() {
                    Ok(Some(_)) => match self.query() {
                        Ok(0) if errors.is_empty() => { drop(self.thread.take()); return Ok(()); }
                        Ok(_) => {}
                        Err(error) if errors.is_empty() => errors.push(format!("job query: {error}")),
                        Err(_) => {}
                    },
                    Ok(None) => {}
                    Err(error) if errors.is_empty() => errors.push(format!("status: {error}")),
                    Err(_) => {}
                }
                // Observation errors do not bypass the owned termination attempt, and an
                // established launch never escalates before its EOF grace has elapsed.
                if Instant::now() >= deadline { break; }
                std::thread::sleep(Duration::from_millis(25));
            }
            if let Err(error) = self.terminate() { errors.push(format!("terminate: {error}")); }
            #[cfg(test)]
            let skip_wait = self.faults.wait;
            #[cfg(not(test))]
            let skip_wait = false;
            if skip_wait { errors.push("wait: injected completion failure".into()); }
            else {
                match unsafe { WaitForSingleObject(self.process.as_raw_handle(), CLEANUP_WAIT.as_millis() as u32) } {
                    WAIT_OBJECT_0 => {}
                    WAIT_TIMEOUT => errors.push("wait: owned process completion not established".into()),
                    _ => errors.push(format!("wait: {}", io::Error::last_os_error())),
                }
            }
            let deadline = Instant::now() + CLEANUP_WAIT;
            loop {
                match self.query() {
                    Ok(0) => break,
                    Ok(_) if Instant::now() < deadline => std::thread::sleep(Duration::from_millis(25)),
                    Ok(_) => { errors.push("job query: owned Job is not empty".into()); break; }
                    Err(error) => { errors.push(format!("job query: {error}")); break; }
                }
            }
            if errors.is_empty() { drop(self.thread.take()); Ok(()) }
            else { Err(io::Error::other(errors.join("; "))) }
        }
    }
    impl ChildProcess for WindowsChild {
        fn id(&self) -> u32 { self.pid }
        fn launch_failed(&self) -> bool { self.failed || self.stopping }
        fn shutdown_requires_channel(&self) -> bool { !self.failed || self.stopping || self.established }
        fn retain_failure(&mut self) { self.failed = true; }
        fn try_wait(&mut self) -> io::Result<Option<ExitStatus>> {
            if self.launch_failed() { return Err(io::Error::other("retained failed launch requires checked shutdown")); }
            self.status()
        }
        fn kill(&mut self) -> io::Result<()> { self.terminate() }
        fn wait(&mut self) -> io::Result<ExitStatus> {
            if self.failed { return Err(io::Error::other("retained failed launch requires checked shutdown")); }
            match unsafe { WaitForSingleObject(self.process.as_raw_handle(), INFINITE) } {
                WAIT_OBJECT_0 => {}
                _ => return Err(io::Error::last_os_error()),
            }
            self.complete(Duration::ZERO)?;
            self.status()?.ok_or_else(|| io::Error::other("owned process completion missing"))
        }
        fn shutdown_owned(&mut self, grace: Duration) -> io::Result<()> {
            if self.completed { return self.finish_record(); }
            if self.failed && !self.stopping && !self.established {
                // Failed startup may never have installed its listener.
                self.complete(grace)?;
                self.completed = true;
                return self.finish_record();
            }
            self.stopping = true;
            // The caller owns the grace; the authenticated attempt never exceeds the cap.
            let deadline = Instant::now() + grace.min(RECOVERED_STOP_LIMIT);
            let graceful = if self.force_requested { false }
                else { self.graceful_owned_until(deadline).is_ok() };
            if !graceful {
                self.force_requested = true;
                // Even an early authentication failure gets the remaining grace. Only
                // the retained exact created process/Job can be terminated, never a PID
                // lookup, discovered process tree, or recovered record's alleged group.
                self.complete(deadline.saturating_duration_since(Instant::now()))?;
                if let Some(stop) = self.stop.as_mut() { stop.settle_owned_io(CLEANUP_WAIT)?; }
            }
            self.completed = true;
            if let Some(record) = self.stop.as_mut().and_then(|stop| stop.record.as_mut()) {
                drop(record.file.take());
            }
            self.finish_record()?;
            drop(self.thread.take());
            eprintln!("gentle-dot: owned Windows shutdown confirmed ({})",
                if graceful { "orderly" } else { "exact-Job fallback" });
            Ok(())
        }
        fn started_owned(&self) -> io::Result<u64> {
            let mut created: FILETIME = unsafe { std::mem::zeroed() };
            let mut exited = created;
            let mut kernel = created;
            let mut user = created;
            unsafe { checked(GetProcessTimes(self.process.as_raw_handle(), &mut created, &mut exited, &mut kernel, &mut user))?; }
            Ok(((created.dwHighDateTime as u64) << 32) | created.dwLowDateTime as u64)
        }
    }
    impl WindowsChild {
        fn graceful_owned_until(&mut self, deadline: Instant) -> io::Result<()> {
            if self.stop.is_none() {
                let published = self.record.as_ref()
                    .ok_or_else(|| recovery_error("owned Windows stop record is unavailable"))?;
                let record = read_validated_record(published.path.parent().ok_or_else(unsafe_record)?)?
                    .ok_or_else(|| recovery_error("owned Windows stop record is absent"))?;
                require_complete_record(published.identity.ok_or_else(unsafe_record)?,
                    &published.expected, record.identity, &record.record)?;
                let process = self.process.try_clone()?;
                self.stop = Some(RecoveredLaunch { record: Some(record), process: Some(process),
                    admitted: false, connect: None, write: None, attempted: false,
                    written: false, clean_exit: false });
                let stop = self.stop.as_mut().unwrap();
                stop.require_live()?;
                stop.admitted = true;
            }
            let stop = self.stop.as_mut().unwrap();
            stop.stop(deadline.saturating_duration_since(Instant::now()))?;
            // Recovery may accept an independently observed clean root exit. Owned
            // shutdown additionally requires a completed authenticated frame. EOF alone
            // is never authority, and clean managed root exit includes daemon fd3 drain.
            if !stop.written || !stop.clean_exit || stop.connect.is_some() || stop.write.is_some() {
                return Err(recovery_error("owned Windows authenticated stop/drain is unconfirmed"));
            }
            while self.query()? != 0 {
                if Instant::now() >= deadline {
                    return Err(recovery_error("owned Windows Job is not empty; record retained"));
                }
                std::thread::sleep(RECOVERY_POLL);
            }
            Ok(())
        }
    }
    impl Drop for WindowsChild {
        fn drop(&mut self) {
            // Ordinary production destruction, not probe proof: best effort only. Preserve
            // configured kill-on-last-Job-close through RAII even if explicit cleanup fails.
            // An unassigned failed child may remain suspended on persistent OS failure;
            // neither error nor closing a process handle is claimed to prove termination.
            if let Err(error) = self.complete(Duration::ZERO) {
                eprintln!("gentle-dot: owned Windows daemon cleanup was not confirmed: {error}");
            }
        }
    }
    #[derive(Debug)]
    pub(crate) struct SpawnFailure {
        pub(crate) primary: io::Error,
        pub(crate) cleanup: Option<io::Error>,
        pub(crate) unfinished: Option<WindowsChild>,
    }
    impl From<io::Error> for SpawnFailure {
        fn from(primary: io::Error) -> Self { Self { primary, cleanup: None, unfinished: None } }
    }
    pub(crate) fn spawn(spec: &LaunchSpec, log: File, channel: &ChildEndpoint, data_dir: &Path) -> Result<WindowsChild, SpawnFailure> {
        #[cfg(test)]
        { spawn_inner(spec, log, channel, data_dir, Faults::default()) }
        #[cfg(not(test))]
        { spawn_inner(spec, log, channel, data_dir) }
    }
    #[cfg(test)]
    fn spawn_with_faults(spec: &LaunchSpec, log: File, channel: &ChildEndpoint, faults: Faults) -> Result<WindowsChild, SpawnFailure> {
        // Existing fault cases fail before publication; no fixture record is created.
        spawn_inner(spec, log, channel, Path::new(""), faults)
    }
    fn spawn_inner(spec: &LaunchSpec, log: File, channel: &ChildEndpoint, data_dir: &Path, #[cfg(test)] faults: Faults) -> Result<WindowsChild, SpawnFailure> {
        let application = application(spec)?;
        let mut command = command_line(&spec.program, &spec.args)?;
        // The CLI must read this exact record directory, not infer another profile.
        // Only the non-secret path is passed; nonce/capability remain file-only.
        let mut launch = spec.clone();
        let directory = data_dir.to_str().ok_or_else(|| io::Error::new(io::ErrorKind::InvalidInput,
            "Windows stop record directory must be Unicode"))?;
        launch.envs.push(("GENTLE_DOT_DATA_DIR".into(), directory.into()));
        let mut env = environment(&launch)?;
        let transfers = Transfers::new(&log, channel)?;
        let mut handles = transfers.handles();
        let mut reserved = transfers.bootstrap()?;
        let mut attributes = Attributes::new(&mut handles)?;
        let job = new_job()?;
        let mut startup: STARTUPINFOEXW = unsafe { std::mem::zeroed() };
        startup.StartupInfo.cb = std::mem::size_of::<STARTUPINFOEXW>() as u32;
        startup.StartupInfo.dwFlags = STARTF_USESTDHANDLES;
        startup.StartupInfo.hStdInput = handles[0];
        startup.StartupInfo.hStdOutput = handles[1];
        startup.StartupInfo.hStdError = handles[2];
        startup.StartupInfo.cbReserved2 = reserved.len() as u16;
        startup.StartupInfo.lpReserved2 = reserved.as_mut_ptr();
        startup.lpAttributeList = attributes.pointer();
        let mut process: PROCESS_INFORMATION = unsafe { std::mem::zeroed() };
        // SAFETY: all UTF-16, packed descriptor, exact handle-list and attribute buffers
        // remain stable through this call. Null cwd preserves the existing inherited cwd.
        unsafe {
            checked(CreateProcessW(application.as_ptr(), command.as_mut_ptr(), null(), null(), 1,
                DAEMON_CREATION_FLAGS,
                env.as_mut_ptr().cast(), null(), &startup.StartupInfo, &mut process))?;
        }
        // CreateProcessW success guarantees these two handles. Acquire both immediately:
        // no fallible operation may strand the created process before its owner exists.
        let mut child = WindowsChild {
            process: unsafe { OwnedHandle::from_raw_handle(process.hProcess) },
            thread: Some(unsafe { OwnedHandle::from_raw_handle(process.hThread) }), job,
            pid: process.dwProcessId, assigned: false, failed: false, established: false, record: None, stop: None, stopping: false,
            force_requested: false, completed: false,
            #[cfg(test)] faults,
        };
        let setup = (|| -> io::Result<()> {
            #[cfg(test)]
            if child.faults.assignment { return Err(io::Error::other("injected assignment failure")); }
            unsafe { checked(AssignProcessToJobObject(child.job.as_raw_handle(), child.process.as_raw_handle()))?; }
            child.assigned = true;
            #[cfg(test)]
            if child.faults.verification { return Err(io::Error::other("injected verification failure")); }
            let mut belongs = 0;
            unsafe { checked(IsProcessInJob(child.process.as_raw_handle(), child.job.as_raw_handle(), &mut belongs))?; }
            if belongs == 0 || job_active(&child.job)? != 1 {
                return Err(io::Error::other("suspended daemon Job ownership not established"));
            }
            // No execution until the exact suspended launch has a protected v1 record.
            // The publication helper installs ownership immediately after CREATE_NEW.
            child.publish_record(data_dir)?;
            // Name this app as the Job's only handle holder before the daemon can run.
            publish_owner(data_dir, &child.record.as_ref().unwrap().expected)?;
            let previous = unsafe { ResumeThread(child.thread.as_ref().unwrap().as_raw_handle()) };
            if previous == u32::MAX { return Err(io::Error::last_os_error()); }
            if previous != 1 { return Err(io::Error::other("unexpected daemon suspension state")); }
            child.established = true;
            drop(child.thread.take());
            Ok(())
        })();
        if let Err(primary) = setup {
            child.failed = true;
            return match child.shutdown_owned(Duration::ZERO) {
                Ok(()) => Err(SpawnFailure { primary, cleanup: None, unfinished: None }),
                Err(cleanup) => Err(SpawnFailure { primary, cleanup: Some(cleanup), unfinished: Some(child) }),
            };
        }
        Ok(child)
    }

    /// Stable opened-file identity for a later independently checked deletion handle.
    /// This is not process identity or permission to delete; unit 3 must also compare
    /// the complete record and establish exact-process clean completion.
    #[derive(Clone, Copy, PartialEq, Eq)]
    pub(crate) struct FileIdentity {
        volume: u64,
        id: [u8; 16],
        created: u64,
    }
    impl FileIdentity {
        fn from_handle(handle: HANDLE, info: &BY_HANDLE_FILE_INFORMATION) -> io::Result<Self> {
            // Require the full filesystem identifier (including ReFS's 128-bit ID),
            // not a truncated legacy file index. Unsupported queries fail closed.
            let mut id: FILE_ID_INFO = unsafe { std::mem::zeroed() };
            unsafe { checked(GetFileInformationByHandleEx(handle, FileIdInfo,
                (&mut id as *mut FILE_ID_INFO).cast(), std::mem::size_of_val(&id) as u32))?; }
            Ok(Self { volume: id.VolumeSerialNumber, id: id.FileId.Identifier,
                created: ((info.ftCreationTime.dwHighDateTime as u64) << 32) | info.ftCreationTime.dwLowDateTime as u64 })
        }
    }

    /// Read-only provenance owner, not a recovered process. No WRITE/DELETE access is
    /// retained: both sharing directions remain compatible with addon startup's
    /// FILE_SHARE_READ record and ancestry opens. No Debug implementation leaks data.
    pub(crate) struct ValidatedRecord {
        pub(crate) record: super::super::windows_record::Record,
        pub(crate) identity: FileIdentity,
        pub(crate) path: PathBuf,
        pub(crate) file: Option<File>,
        deletion_marked: bool,
        // No delete sharing pins every path component through validation and future
        // use. Keep these guards when replacing the record reader with a deletion
        // handle; that handle must be validated anew, not trusted by pathname.
        _ancestry: Vec<OwnedHandle>,
    }

    fn require_complete_record(expected_identity: FileIdentity, expected: &super::super::windows_record::Record,
        observed_identity: FileIdentity, observed: &super::super::windows_record::Record) -> io::Result<()> {
        if expected_identity != observed_identity || expected != observed { return Err(unsafe_record()); }
        Ok(())
    }

    struct SecuritySnapshot(PSECURITY_DESCRIPTOR);
    impl Drop for SecuritySnapshot {
        fn drop(&mut self) { unsafe { LocalFree(self.0) }; }
    }
    fn unsafe_record() -> io::Error {
        io::Error::new(io::ErrorKind::InvalidData, "unsafe Windows stop record provenance")
    }

    // Aligned buffers are required before interpreting TOKEN_USER or passing SID
    // pointers to Windows. Byte vectors alone do not promise this alignment.
    fn current_user_sid() -> io::Result<Vec<usize>> {
        let mut token = null_mut();
        unsafe { checked(OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token))?; }
        let token = owned(token)?;
        let mut size = 0;
        let result = unsafe { GetTokenInformation(token.as_raw_handle(), TokenUser, null_mut(), 0, &mut size) };
        let error = io::Error::last_os_error();
        if result != 0 || error.raw_os_error() != Some(ERROR_INSUFFICIENT_BUFFER as i32)
            || size < std::mem::size_of::<TOKEN_USER>() as u32 || size > 65_536 {
            return Err(unsafe_record());
        }
        let mut data = vec![0usize; (size as usize).div_ceil(std::mem::size_of::<usize>())];
        unsafe {
            checked(GetTokenInformation(token.as_raw_handle(), TokenUser, data.as_mut_ptr().cast(), size, &mut size))?;
            let sid = (*(data.as_ptr().cast::<TOKEN_USER>())).User.Sid;
            if IsValidSid(sid) == 0 { return Err(unsafe_record()); }
            let length = GetLengthSid(sid);
            if length == 0 || length > SECURITY_MAX_SID_SIZE as u32 { return Err(unsafe_record()); }
            let mut copy = vec![0usize; (length as usize).div_ceil(std::mem::size_of::<usize>())];
            checked(CopySid(length, copy.as_mut_ptr().cast(), sid))?;
            Ok(copy)
        }
    }

    fn validate_record_security(handle: HANDLE, expected: PSID) -> io::Result<()> {
        let mut owner = null_mut();
        let mut acl = null_mut();
        let mut descriptor = null_mut();
        let result = unsafe { GetSecurityInfo(handle, SE_FILE_OBJECT,
            OWNER_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION,
            &mut owner, null_mut(), &mut acl, null_mut(), &mut descriptor) };
        if result != ERROR_SUCCESS { return Err(io::Error::from_raw_os_error(result as i32)); }
        let _snapshot = SecuritySnapshot(descriptor);
        if descriptor.is_null() { return Err(unsafe_record()); }
        let mut control = 0;
        let mut revision = 0;
        // SAFETY: GetSecurityInfo owns the returned descriptor, ACL and owner SID;
        // the snapshot retains their allocation through every inspection below.
        unsafe {
            if owner.is_null() || IsValidSid(owner) == 0 || EqualSid(owner, expected) == 0
                || acl.is_null() || IsValidAcl(acl) == 0
                || GetSecurityDescriptorControl(descriptor, &mut control, &mut revision) == 0
                || control & SE_DACL_PROTECTED as u16 == 0 || (*acl).AceCount == 0 {
                return Err(unsafe_record());
            }
            for index in 0..(*acl).AceCount {
                let mut raw = null_mut();
                checked(GetAce(acl, index as u32, &mut raw))?;
                if raw.is_null() { return Err(unsafe_record()); }
                let header = &*raw.cast::<ACE_HEADER>();
                // ACCESS_ALLOWED_ACE has an 8-byte prefix, then a variable SID.
                // Bound the SID header and subauthorities before IsValidSid reads it.
                const SID_OFFSET: usize = std::mem::offset_of!(ACCESS_ALLOWED_ACE, SidStart);
                if header.AceType as u32 != ACCESS_ALLOWED_ACE_TYPE as u32 || header.AceFlags != 0
                    || (header.AceSize as usize) < SID_OFFSET + 8 {
                    return Err(unsafe_record());
                }
                let sid_bytes = raw.cast::<u8>().add(SID_OFFSET);
                let count = *sid_bytes.add(1) as usize;
                if count > SID_MAX_SUB_AUTHORITIES as usize
                    || (header.AceSize as usize) != SID_OFFSET + 8 + 4 * count {
                    return Err(unsafe_record());
                }
                let sid = sid_bytes.cast();
                if IsValidSid(sid) == 0 || EqualSid(sid, expected) == 0 {
                    return Err(unsafe_record());
                }
            }
        }
        Ok(())
    }

    fn file_info(handle: HANDLE) -> io::Result<BY_HANDLE_FILE_INFORMATION> {
        let mut info = unsafe { std::mem::zeroed() };
        unsafe { checked(GetFileInformationByHandle(handle, &mut info))?; }
        if unsafe { GetFileType(handle) } != FILE_TYPE_DISK
            || info.dwFileAttributes & FILE_ATTRIBUTE_REPARSE_POINT != 0 {
            return Err(unsafe_record());
        }
        Ok(info)
    }

    fn record_ancestry(path: &Path, create_missing: bool) -> io::Result<Vec<OwnedHandle>> {
        let name = wide(path.as_os_str())?;
        let text = &name[..name.len() - 1];
        if text.len() < 4 || text[1] != b':' as u16 || text[2] != b'\\' as u16
            || !((b'A' as u16..=b'Z' as u16).contains(&text[0])
                || (b'a' as u16..=b'z' as u16).contains(&text[0])) {
            return Err(unsafe_record());
        }
        let root = [text[0], text[1], text[2], 0];
        if unsafe { GetDriveTypeW(root.as_ptr()) } != DRIVE_FIXED { return Err(unsafe_record()); }
        let sid = current_user_sid()?;
        let expected = sid.as_ptr() as PSID;
        let mut ancestry = Vec::new();
        // Include the drive root. Every ancestor is opened with read-only access
        // and no write/delete sharing, and kept alive in the returned owner.
        let root_handle = owned(unsafe { CreateFileW(root.as_ptr(), FILE_READ_ATTRIBUTES,
            FILE_SHARE_READ, null(), OPEN_EXISTING,
            FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) })?;
        if file_info(root_handle.as_raw_handle())?.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY == 0 {
            return Err(unsafe_record());
        }
        ancestry.push(root_handle);
        let mut start = 3;
        for end in 3..=text.len() {
            if end != text.len() && text[end] != b'\\' as u16 { continue; }
            let component = &text[start..end];
            if component.is_empty() || component == [b'.' as u16] || component == [b'.' as u16, b'.' as u16]
                || component.iter().any(|ch| *ch < 32 || [b':' as u16, b'/' as u16,
                    b'*' as u16, b'?' as u16, b'"' as u16, b'<' as u16, b'>' as u16, b'|' as u16].contains(ch))
                || matches!(component.last(), Some(ch) if *ch == b'.' as u16 || *ch == b' ' as u16) {
                return Err(unsafe_record());
            }
            start = end + 1;
            if end == text.len() { break; }
            let mut prefix = text[..end].to_vec(); prefix.push(0);
            let mut raw = unsafe { CreateFileW(prefix.as_ptr(), FILE_READ_ATTRIBUTES,
                FILE_SHARE_READ, null(), OPEN_EXISTING,
                FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) };
            if raw == INVALID_HANDLE_VALUE && create_missing {
                let error = io::Error::last_os_error();
                if error.raw_os_error() != Some(ERROR_FILE_NOT_FOUND as i32)
                    && error.raw_os_error() != Some(ERROR_PATH_NOT_FOUND as i32) { return Err(error); }
                // Create only absent components, beneath already retained ancestry.
                // Existing directories are never repaired by admission/validation.
                let descriptor = Descriptor::for_user(expected)?;
                if unsafe { CreateDirectoryW(prefix.as_ptr(), &descriptor.attributes()) } == 0 {
                    let error = io::Error::last_os_error();
                    if error.raw_os_error() != Some(ERROR_ALREADY_EXISTS as i32) { return Err(error); }
                }
                raw = unsafe { CreateFileW(prefix.as_ptr(), FILE_READ_ATTRIBUTES,
                    FILE_SHARE_READ, null(), OPEN_EXISTING,
                    FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) };
            }
            let directory = owned(raw)?;
            if file_info(directory.as_raw_handle())?.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY == 0 {
                return Err(unsafe_record());
            }
            ancestry.push(directory);
        }
        Ok(ancestry)
    }

    /// First-run directory creation is separate from read-only validation and never
    /// repairs an existing object. Every missing component gets a literal-user DACL.
    pub(crate) fn ensure_record_directory(data_dir: &Path) -> io::Result<()> {
        record_ancestry(&data_dir.join(super::super::PID_FILE), true).map(drop)
    }

    fn read_protected(file: &mut File, max: usize) -> io::Result<(Vec<u8>, FileIdentity)> {
        use std::io::{Read, Seek};
        let sid = current_user_sid()?;
        let info = file_info(file.as_raw_handle())?;
        let length = ((info.nFileSizeHigh as u64) << 32) | info.nFileSizeLow as u64;
        if info.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY != 0 || length == 0 || length > max as u64 {
            return Err(unsafe_record());
        }
        validate_record_security(file.as_raw_handle(), sid.as_ptr() as PSID)?;
        let identity = FileIdentity::from_handle(file.as_raw_handle(), &info)?;
        file.rewind()?;
        let mut bytes = Vec::with_capacity(max + 1);
        (&mut *file).take((max + 1) as u64).read_to_end(&mut bytes)?;
        if bytes.len() as u64 != length { return Err(unsafe_record()); }
        let after = file_info(file.as_raw_handle())?;
        if FileIdentity::from_handle(file.as_raw_handle(), &after)? != identity
            || after.nFileSizeHigh != info.nFileSizeHigh || after.nFileSizeLow != info.nFileSizeLow {
            return Err(unsafe_record());
        }
        Ok((bytes, identity))
    }

    fn read_record_file(file: &mut File) -> io::Result<(super::super::windows_record::Record, FileIdentity)> {
        use super::super::windows_record::{Record, MAX_BYTES};
        let (bytes, identity) = read_protected(file, MAX_BYTES)?;
        Ok((Record::parse(&bytes)?, identity))
    }

    const OWNER_FILE: &str = "daemon.owner";

    fn read_owner_file(file: &mut File) -> io::Result<super::super::windows_record::Owner> {
        use super::super::windows_record::{Owner, OWNER_MAX_BYTES};
        Owner::parse(&read_protected(file, OWNER_MAX_BYTES)?.0)
    }

    fn process_created(handle: HANDLE) -> io::Result<u64> {
        let mut created: FILETIME = unsafe { std::mem::zeroed() };
        let mut exited = created;
        let mut kernel = created;
        let mut user = created;
        unsafe { checked(GetProcessTimes(handle, &mut created, &mut exited, &mut kernel, &mut user))?; }
        Ok(((created.dwHighDateTime as u64) << 32) | created.dwLowDateTime as u64)
    }

    /// Written only while this launch exclusively holds its newly created record and
    /// before the daemon resumes. A previous launch's witness, left without its record,
    /// has no authority and is removed by handle without following a reparse point.
    fn publish_owner(data_dir: &Path, record: &super::super::windows_record::Record) -> io::Result<()> {
        use super::super::windows_record::Owner;
        use std::io::Write;
        let path = data_dir.join(OWNER_FILE);
        let _ancestry = record_ancestry(&path, false)?;
        let name = wide(path.as_os_str())?;
        let stale = unsafe { CreateFileW(name.as_ptr(), DELETE | FILE_READ_ATTRIBUTES, FILE_SHARE_READ,
            null(), OPEN_EXISTING, FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) };
        if stale == INVALID_HANDLE_VALUE {
            let error = io::Error::last_os_error();
            if error.raw_os_error() != Some(ERROR_FILE_NOT_FOUND as i32) { return Err(error); }
        } else {
            let stale = owned(stale)?;
            let disposition = FILE_DISPOSITION_INFO { DeleteFile: true };
            unsafe { checked(SetFileInformationByHandle(stale.as_raw_handle(), FileDispositionInfo,
                (&disposition as *const FILE_DISPOSITION_INFO).cast(), std::mem::size_of_val(&disposition) as u32))?; }
        }
        let owner = Owner::new(record.nonce(), unsafe { GetCurrentProcessId() },
            process_created(unsafe { GetCurrentProcess() })?)?;
        let sid = current_user_sid()?;
        let descriptor = Descriptor::for_user(sid.as_ptr() as PSID)?;
        // CREATE_NEW also fails while another reader defers the stale file's deletion.
        let mut file = File::from(owned(unsafe { CreateFileW(name.as_ptr(), GENERIC_READ | GENERIC_WRITE | READ_CONTROL,
            FILE_SHARE_READ, &descriptor.attributes(), CREATE_NEW,
            FILE_ATTRIBUTE_NORMAL | FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) })?);
        file.write_all(&owner.encode())?;
        file.sync_all()?;
        if read_owner_file(&mut file)? != owner { return Err(unsafe_record()); }
        Ok(())
    }

    fn read_validated_owner(data_dir: &Path) -> io::Result<Option<super::super::windows_record::Owner>> {
        let path = data_dir.join(OWNER_FILE);
        let _ancestry = record_ancestry(&path, false)?;
        let name = wide(path.as_os_str())?;
        let raw = unsafe { CreateFileW(name.as_ptr(), GENERIC_READ | READ_CONTROL, FILE_SHARE_READ,
            null(), OPEN_EXISTING, FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) };
        if raw == INVALID_HANDLE_VALUE {
            let error = io::Error::last_os_error();
            if error.raw_os_error() == Some(ERROR_FILE_NOT_FOUND as i32) { return Ok(None); }
            return Err(error);
        }
        read_owner_file(&mut File::from(owned(raw)?)).map(Some)
    }

    fn snapshot_contains(pid: u32) -> io::Result<bool> {
        let snapshot = owned(unsafe { CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0) })?;
        let mut entry: PROCESSENTRY32W = unsafe { std::mem::zeroed() };
        entry.dwSize = std::mem::size_of::<PROCESSENTRY32W>() as u32;
        unsafe { checked(Process32FirstW(snapshot.as_raw_handle(), &mut entry))?; }
        loop {
            if entry.th32ProcessID == pid { return Ok(true); }
            if unsafe { Process32NextW(snapshot.as_raw_handle(), &mut entry) } == 0 {
                let error = io::Error::last_os_error();
                if error.raw_os_error() == Some(ERROR_NO_MORE_FILES as i32) { return Ok(false); }
                return Err(error);
            }
        }
    }

    enum Observed { Gone, Exited, Running(OwnedHandle) }
    /// Exact-identity state, never a termination route. OpenProcess error 87 alone is
    /// not absence: a full process snapshot must also lack the PID. A different creation
    /// time means the PID was reused, which the recorded process object cannot outlive.
    fn observe_process(pid: u32, created: u64) -> io::Result<Observed> {
        let raw = unsafe { OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION | SYNCHRONIZE, 0, pid) };
        if raw.is_null() {
            let error = io::Error::last_os_error();
            if error.raw_os_error() == Some(ERROR_INVALID_PARAMETER as i32) && !snapshot_contains(pid)? {
                return Ok(Observed::Gone);
            }
            return Err(error);
        }
        let process = owned(raw)?;
        if process_created(process.as_raw_handle())? != created { return Ok(Observed::Gone); }
        match unsafe { WaitForSingleObject(process.as_raw_handle(), 0) } {
            WAIT_OBJECT_0 => Ok(Observed::Exited),
            WAIT_TIMEOUT => Ok(Observed::Running(process)),
            _ => Err(io::Error::last_os_error()),
        }
    }

    /// Retires a stop record only when its bound witness names an app process that has
    /// exited. That process held the only handle to the launch's KILL_ON_JOB_CLOSE Job, and
    /// Windows closes a process's handles before signaling its exit, so the kernel already
    /// terminated every process in that Job. Nothing is terminated here; processes created
    /// outside the Job (WMI, Task Scheduler, COM) were never part of the owned group.
    ///
    /// Ok(false) only when there is no readable record or no witness at all (a legacy v1
    /// launch), which keeps the existing admission route. A witnessed launch whose owner
    /// lives, or whose witness is invalid, unbound or unverifiable, is refused: the recovered
    /// stop route proves only root exit, and a live owner keeps its Job's descendants alive.
    pub(crate) fn retire_if_owner_exited(data_dir: &Path) -> io::Result<bool> {
        let Ok(Some(mut record)) = read_validated_record(data_dir) else { return Ok(false) };
        let owner = match read_validated_owner(data_dir) {
            Ok(None) => return Ok(false),
            Ok(Some(owner)) => owner,
            Err(_) => return Err(recovery_error("Windows owner witness is invalid or unreadable; record retained")),
        };
        if !owner.binds(&record.record) {
            return Err(recovery_error("Windows owner witness does not match the recorded launch; record retained"));
        }
        match observe_process(owner.pid, owner.created) {
            Ok(Observed::Gone | Observed::Exited) => {}
            Ok(Observed::Running(_)) => return Err(recovery_error(
                "the previous launch's owning app is still running; record retained")),
            Err(_) => return Err(recovery_error("Windows owner state is unverifiable; record retained")),
        }
        // Termination is asynchronous and waits for pending I/O: never overlap a root that
        // is still finishing. A root that keeps running contradicts the proof; refuse.
        match observe_process(record.record.pid, record.record.created)? {
            Observed::Gone | Observed::Exited => {}
            Observed::Running(root) => match unsafe {
                WaitForSingleObject(root.as_raw_handle(), RECOVERED_STOP_LIMIT.as_millis() as u32)
            } {
                WAIT_OBJECT_0 => {}
                WAIT_TIMEOUT => return Err(recovery_error(
                    "recorded Windows root is still running after its owner exited; record retained")),
                _ => return Err(io::Error::last_os_error()),
            },
        }
        delete_exact_record(&record.path, &record.record, record.identity, &mut record.file, &mut record.deletion_marked)?;
        Ok(true)
    }

    // The validation/live stages cover multiple checks; they do not identify a syscall.
    #[derive(Clone, Copy, Debug)]
    enum AcquisitionStage {
        RecordAncestry,
        RecordName,
        RecordOpen,
        RecordValidation,
        ProcessOpen,
        ProcessAdmission,
    }
    impl AcquisitionStage {
        fn label(self) -> &'static str {
            match self {
                Self::RecordAncestry => "validate record ancestry",
                Self::RecordName => "encode record name",
                Self::RecordOpen => "open record (CreateFileW)",
                Self::RecordValidation => "validate opened record (security, contents and file identity)",
                Self::ProcessOpen => "open recorded process (OpenProcess)",
                Self::ProcessAdmission => "check recorded process identity and liveness",
            }
        }
        fn error(self, source: io::Error) -> io::Error {
            io::Error::new(source.kind(), AcquisitionError { stage: self, source })
        }
    }
    #[derive(Debug)]
    struct AcquisitionError {
        stage: AcquisitionStage,
        source: io::Error,
    }
    impl std::fmt::Display for AcquisitionError {
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            write!(f, "{}: {}", self.stage.label(), self.source)
        }
    }
    impl std::error::Error for AcquisitionError {
        fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.source) }
    }
    // io::Error::new retains kind, but its raw_os_error() is None. Retrieve the
    // original io::Error (and native code) via std::error::Error::source instead.

    /// Only a genuinely absent final record is None; unsafe/missing ancestry remains
    /// an error. Validation never creates, repairs, deletes or checks process liveness.
    pub(crate) fn read_validated_record(data_dir: &Path) -> io::Result<Option<ValidatedRecord>> {
        let path = data_dir.join(super::super::PID_FILE);
        let ancestry = record_ancestry(&path, false).map_err(|error| AcquisitionStage::RecordAncestry.error(error))?;
        let name = wide(path.as_os_str()).map_err(|error| AcquisitionStage::RecordName.error(error))?;
        let raw = unsafe { CreateFileW(name.as_ptr(), GENERIC_READ | READ_CONTROL, FILE_SHARE_READ,
            null(), OPEN_EXISTING, FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) };
        if raw == INVALID_HANDLE_VALUE {
            let error = io::Error::last_os_error();
            if error.raw_os_error() == Some(ERROR_FILE_NOT_FOUND as i32) { return Ok(None); }
            return Err(AcquisitionStage::RecordOpen.error(error));
        }
        let mut file = File::from(owned(raw).map_err(|error| AcquisitionStage::RecordOpen.error(error))?);
        let (record, identity) = read_record_file(&mut file)
            .map_err(|error| AcquisitionStage::RecordValidation.error(error))?;
        Ok(Some(ValidatedRecord { record, identity, path, file: Some(file), deletion_marked: false, _ancestry: ancestry }))
    }

    // Hard cap on any caller's stop budget: the stop deadline is also how long a
    // capability-bearing connection may be pending. Callers choose their own grace
    // (the lifecycle passes its shutdown grace); this module only shortens it.
    const RECOVERED_STOP_LIMIT: Duration = Duration::from_secs(10);
    const RECOVERY_POLL: Duration = Duration::from_millis(10);

    fn recovery_error(message: &'static str) -> io::Error { io::Error::other(message) }
    fn require_launch_identity(pid: u32, created: u64, observed_pid: u32, observed_created: u64) -> io::Result<()> {
        if pid != observed_pid || created != observed_created {
            return Err(recovery_error("recorded Windows process identity does not match"));
        }
        Ok(())
    }
    fn require_frame_size(transferred: u32) -> io::Result<()> {
        if transferred != 36 { return Err(recovery_error("Windows stop frame was not written exactly")); }
        Ok(())
    }

    /// Failure is not absence. Even a failed OpenProcess retains validated provenance;
    /// identity mismatch/death retains the opened handle without admitting a stop request.
    /// Neither this error nor its owner implements Debug (the record holds a capability).
    pub(crate) struct RecoveryFailure {
        pub(crate) error: io::Error,
        pub(crate) retained: Option<RecoveredLaunch>,
    }
    pub(crate) struct RecoveredLaunch {
        record: Option<ValidatedRecord>,
        process: Option<OwnedHandle>,
        admitted: bool,
        connect: Option<ConnectAttempt>,
        write: Option<PendingStopWrite>,
        attempted: bool,
        written: bool,
        clean_exit: bool,
    }

    pub(crate) fn acquire_recovered_launch(data_dir: &Path) -> Result<Option<RecoveredLaunch>, RecoveryFailure> {
        let record = match read_validated_record(data_dir) {
            Ok(None) => return Ok(None),
            Ok(Some(record)) => record,
            Err(error) => return Err(RecoveryFailure { error, retained: None }),
        };
        let mut owner = RecoveredLaunch { record: Some(record), process: None, admitted: false,
            connect: None, write: None, attempted: false, written: false, clean_exit: false };
        let acquisition = (|| -> io::Result<()> {
            let pid = owner.record.as_ref().unwrap().record.pid;
            // Exactly one non-inheritable open. No termination, enumeration, privilege
            // adjustment, or reopen-by-PID path exists, including on acquisition failure.
            owner.process = Some(owned(unsafe { OpenProcess(
                PROCESS_QUERY_LIMITED_INFORMATION | SYNCHRONIZE, 0, pid) })
                .map_err(|error| AcquisitionStage::ProcessOpen.error(error))?);
            owner.require_live().map_err(|error| AcquisitionStage::ProcessAdmission.error(error))?;
            owner.admitted = true;
            Ok(())
        })();
        match acquisition {
            Ok(()) => Ok(Some(owner)),
            Err(error) => Err(RecoveryFailure { error, retained: Some(owner) }),
        }
    }

    impl RecoveredLaunch {
        fn process_handle(&self) -> io::Result<HANDLE> {
            self.process.as_ref().map(AsRawHandle::as_raw_handle)
                .ok_or_else(|| recovery_error("recorded Windows process handle was not acquired"))
        }
        fn require_identity(&self) -> io::Result<HANDLE> {
            let handle = self.process_handle()?;
            let pid = unsafe { GetProcessId(handle) };
            if pid == 0 { return Err(io::Error::last_os_error()); }
            let mut created: FILETIME = unsafe { std::mem::zeroed() };
            let mut exited = created; let mut kernel = created; let mut user = created;
            unsafe { checked(GetProcessTimes(handle, &mut created, &mut exited, &mut kernel, &mut user))?; }
            let record = &self.record.as_ref().unwrap().record;
            require_launch_identity(record.pid, record.created, pid,
                ((created.dwHighDateTime as u64) << 32) | created.dwLowDateTime as u64)?;
            Ok(handle)
        }
        fn require_live(&self) -> io::Result<()> {
            let handle = self.require_identity()?;
            match unsafe { WaitForSingleObject(handle, 0) } {
                WAIT_TIMEOUT => Ok(()),
                WAIT_OBJECT_0 => Err(recovery_error("recorded Windows process is already exited")),
                _ => Err(io::Error::last_os_error()),
            }
        }
        fn observe_exit(&mut self) -> io::Result<bool> {
            let handle = self.require_identity()?;
            match unsafe { WaitForSingleObject(handle, 0) } {
                WAIT_TIMEOUT => Ok(false),
                WAIT_OBJECT_0 => {
                    let mut code = 0;
                    unsafe { checked(GetExitCodeProcess(handle, &mut code))?; }
                    if code != 0 { return Err(recovery_error("recorded Windows process did not exit cleanly")); }
                    self.clean_exit = true;
                    Ok(true)
                }
                _ => Err(io::Error::last_os_error()),
            }
        }
        pub(crate) fn delete_record(&mut self) -> io::Result<()> {
            if !self.clean_exit || self.connect.is_some() || self.write.is_some() || !self.observe_exit()? {
                return Err(recovery_error("recorded Windows clean exit/client drain is not established"));
            }
            let record = self.record.as_mut().unwrap();
            // Ancestry stays installed while the read guard is replaced by a separately
            // validated DELETE handle. Root completion never stands for descendant proof.
            delete_exact_record(&record.path, &record.record, record.identity,
                &mut record.file, &mut record.deletion_marked)
        }

        fn stop_until(&mut self, deadline: Instant) -> io::Result<()> {
            if !self.admitted { return Err(recovery_error("recorded Windows launch was not admitted")); }
            loop {
                // Resolve outstanding open/write results before considering clean exit.
                // Open-result delivery is not thread termination: worker owners remain
                // process-lifetime retained. Root exit never proves I/O cancellation.
                if let Some(write) = self.write.as_mut() {
                    if let Some(result) = write.poll()? {
                        self.write.take();
                        result?;
                        self.written = true;
                    }
                }
                if let Some(connect) = self.connect.as_mut() {
                    if let Some(result) = connect.poll()? {
                        self.connect.take();
                        let pipe = result?;
                        // A clean exit before the server check already achieved the stop.
                        // Return without writing: the opened pipe is dropped unauthenticated.
                        if self.observe_exit()? { return Ok(()); }
                        if Instant::now() >= deadline {
                            return Err(io::Error::new(io::ErrorKind::TimedOut, "Windows stop connection deadline elapsed"));
                        }
                        let mut server = 0;
                        unsafe { checked(GetNamedPipeServerProcessId(pipe.as_raw_handle(), &mut server))?; }
                        let process = self.require_identity()?;
                        if server != unsafe { GetProcessId(process) } {
                            return Err(recovery_error("Windows stop pipe server identity does not match"));
                        }
                        // Verify the retained exact handle again immediately before send.
                        self.require_live()?;
                        if Instant::now() >= deadline {
                            return Err(io::Error::new(io::ErrorKind::TimedOut, "Windows stop write deadline elapsed"));
                        }
                        let frame = self.record.as_ref().unwrap().record.frame();
                        self.attempted = true;
                        self.write = Some(PendingStopWrite::submit(pipe, frame)?);
                    }
                }
                if self.connect.is_none() && self.write.is_none() {
                    if self.observe_exit()? { return Ok(()); }
                    if self.attempted && !self.written {
                        return Err(recovery_error("Windows stop write failed; replacement remains refused"));
                    }
                    if !self.attempted && Instant::now() < deadline {
                        self.require_live()?;
                        let name = wide(std::ffi::OsStr::new(&self.record.as_ref().unwrap().record.pipe_name()))?;
                        self.connect = Some(ConnectAttempt::start(name, deadline)?);
                    }
                }
                let remaining = deadline.saturating_duration_since(Instant::now());
                if remaining.is_zero() {
                    return Err(io::Error::new(io::ErrorKind::TimedOut, "recorded Windows stop completion was not established"));
                }
                std::thread::sleep(RECOVERY_POLL.min(remaining));
            }
        }
        // Owned fallback only: settle native operations, not authenticated delivery or
        // worker/TLS retirement. ConnectAttempt retains its pinned inert worker lifetime.
        fn settle_owned_io(&mut self, timeout: Duration) -> io::Result<()> {
            let deadline = Instant::now() + timeout;
            if let Some(connect) = &self.connect { connect.cancel(); }
            if let Some(write) = &self.write { write.cancel()?; }
            loop {
                if let Some(connect) = &mut self.connect {
                    match connect.result.try_recv() {
                        Ok(result) => {
                            // A late open is closed, never converted into a stop write.
                            drop(result);
                            self.connect.take();
                        }
                        Err(std::sync::mpsc::TryRecvError::Empty) => {}
                        Err(std::sync::mpsc::TryRecvError::Disconnected) => return Err(recovery_error(
                            "owned Windows stop connection result is unconfirmed")),
                    }
                }
                if let Some(write) = &mut self.write {
                    if write.poll()?.is_some() {
                        // Both delivered and aborted writes have ended kernel ownership.
                        self.write.take();
                    }
                }
                if self.connect.is_none() && self.write.is_none() { return Ok(()); }
                let remaining = deadline.saturating_duration_since(Instant::now());
                if remaining.is_zero() {
                    return Err(io::Error::new(io::ErrorKind::TimedOut,
                        "owned Windows stop I/O completion is unconfirmed"));
                }
                std::thread::sleep(RECOVERY_POLL.min(remaining));
            }
        }
        /// One total bounded budget for connection, asynchronous write, and exact-root
        /// clean exit. Errors keep this owner installed; retries never reopen its PID or
        /// resend an uncertain/failed frame. No record is mutated by this method.
        pub(crate) fn stop(&mut self, timeout: Duration) -> io::Result<()> {
            let result = self.stop_until(Instant::now() + timeout.min(RECOVERED_STOP_LIMIT));
            if result.is_err() {
                if let Some(connect) = &self.connect { connect.cancel(); }
                if let Some(write) = &self.write {
                    if let Err(cancel) = write.cancel() {
                        return Err(recovery_error_with_cancel(result.unwrap_err(), cancel));
                    }
                }
            }
            result
        }
    }
    fn recovery_error_with_cancel(primary: io::Error, cancel: io::Error) -> io::Error {
        io::Error::other(format!("{primary}; Windows stop cancellation unconfirmed: {cancel}"))
    }
    impl Drop for RecoveredLaunch {
        fn drop(&mut self) {
            if self.connect.is_some() || self.write.is_some() {
                if let Some(connect) = &self.connect { connect.cancel(); }
                if let Some(write) = &self.write { let _ = write.cancel(); }
                // Defensive process-lifetime retention if a caller discards uncertainty.
                // Preserve provenance/process AND native/thread I/O owners together;
                // never join, close handles, or free kernel-referenced storage here.
                std::mem::forget(Box::new((self.record.take(), self.process.take(),
                    self.connect.take(), self.write.take())));
            }
        }
    }

    fn pin_recovery_module() -> io::Result<()> {
        // LibraryLoader is not an enabled windows-sys feature. Bind only this
        // documented Kernel32 ABI locally, without changing dependency features.
        // FROM_ADDRESS interprets lpModuleName as a code address, not a string;
        // PIN keeps our worker/drop code loaded until process exit, even in a DLL.
        #[link(name = "kernel32")]
        unsafe extern "system" {
            fn GetModuleHandleExW(flags: u32, address: *const u16, module: *mut HMODULE) -> i32;
        }
        const FROM_ADDRESS: u32 = 0x00000004;
        const PIN: u32 = 0x00000001;
        let mut module = null_mut();
        unsafe { checked(GetModuleHandleExW(FROM_ADDRESS | PIN,
            pin_recovery_module as *const () as *const u16, &mut module))?; }
        if module.is_null() { return Err(recovery_error("Windows recovery module lifetime was not retained")); }
        Ok(())
    }

    /// FILE_FLAG_OVERLAPPED does not make CreateFileW itself cancellable. Isolate
    /// that open on an explicitly owned worker; the controller never blocks joining it.
    /// At most one unresolved open exists per retained recovered owner. Workers never
    /// send frames; after result delivery their lifetime is retained until process exit.
    struct ConnectAttempt {
        thread: Option<std::thread::JoinHandle<()>>,
        result: std::sync::mpsc::Receiver<io::Result<OwnedHandle>>,
        cancelled: std::sync::Arc<std::sync::atomic::AtomicBool>,
    }
    impl ConnectAttempt {
        fn start(name: Vec<u16>, deadline: Instant) -> io::Result<Self> {
            use std::sync::atomic::{AtomicBool, Ordering};
            pin_recovery_module()?;
            let cancelled = std::sync::Arc::new(AtomicBool::new(false));
            let flag = cancelled.clone();
            let (sender, result) = std::sync::mpsc::channel();
            let thread = std::thread::Builder::new().name("gentle-dot-stop-connect".into()).spawn(move || {
                let outcome = (|| -> io::Result<OwnedHandle> {
                    loop {
                        if flag.load(Ordering::Acquire) || Instant::now() >= deadline {
                            return Err(io::Error::new(io::ErrorKind::TimedOut, "Windows stop pipe connection unfinished"));
                        }
                        // Derived local name only. Narrow WRITE_DATA omits CREATE_PIPE_INSTANCE;
                        // null security attributes means non-inheritable. Identification SQOS
                        // prevents the server acquiring an impersonation/delegation token.
                        let raw = unsafe { CreateFileW(name.as_ptr(), FILE_WRITE_DATA, 0, null(), OPEN_EXISTING,
                            FILE_FLAG_OVERLAPPED | SECURITY_SQOS_PRESENT | SECURITY_IDENTIFICATION, null_mut()) };
                        if raw != INVALID_HANDLE_VALUE { return owned(raw); }
                        let error = io::Error::last_os_error();
                        if !matches!(error.raw_os_error(), Some(code) if code == ERROR_PIPE_BUSY as i32 || code == ERROR_FILE_NOT_FOUND as i32) {
                            return Err(error);
                        }
                        std::thread::sleep(RECOVERY_POLL.min(deadline.saturating_duration_since(Instant::now())));
                    }
                })();
                let _ = sender.send(outcome);
            })?;
            Ok(Self { thread: Some(thread), result, cancelled })
        }
        fn cancel(&self) { self.cancelled.store(true, std::sync::atomic::Ordering::Release); }
        fn poll(&mut self) -> io::Result<Option<io::Result<OwnedHandle>>> {
            // Delivery transfers the sole open result, not thread/TLS completion.
            // Neither is_finished nor join can establish a bounded retirement here.
            match self.result.try_recv() {
                Ok(result) => Ok(Some(result)),
                Err(std::sync::mpsc::TryRecvError::Empty) => Ok(None),
                Err(std::sync::mpsc::TryRecvError::Disconnected) =>
                    Ok(Some(Err(recovery_error("Windows stop connection result was not retained")))),
            }
        }
    }
    impl Drop for ConnectAttempt {
        fn drop(&mut self) {
            self.cancel();
            if self.thread.is_some() {
                // No portable nonblocking proof of OS-thread/TLS retirement exists.
                // Retain the worker, receiver and cancellation state until process exit,
                // even after delivery/disconnection. An unconsumed late handle stays
                // owned in the queue; the already-pinned module cannot unload beneath
                // the worker. Never join in the deadline-bearing controller or Drop.
                let (sender, empty) = std::sync::mpsc::channel(); drop(sender);
                std::mem::forget(Box::new((self.thread.take(),
                    std::mem::replace(&mut self.result, empty), self.cancelled.clone())));
            }
        }
    }

    struct StopWriteStorage {
        operation: std::cell::UnsafeCell<OVERLAPPED>,
        frame: [u8; 36],
        _event: OwnedHandle,
        pipe: OwnedHandle,
    }
    // SAFETY: the unique controller may move the Box between threads, never its
    // allocation. Only Windows accesses the mutable OVERLAPPED through UnsafeCell;
    // frame/event/pipe remain stable until independently observed completion.
    unsafe impl Send for StopWriteStorage {}
    struct PendingStopWrite { storage: Option<Box<StopWriteStorage>> }
    impl PendingStopWrite {
        fn submit(pipe: OwnedHandle, frame: [u8; 36]) -> io::Result<Self> {
            let event = owned(unsafe { CreateEventW(null(), 1, 0, null()) })?;
            let mut operation: OVERLAPPED = unsafe { std::mem::zeroed() };
            operation.hEvent = event.as_raw_handle();
            let mut this = Self { storage: Some(Box::new(StopWriteStorage {
                operation: std::cell::UnsafeCell::new(operation), frame, _event: event, pipe })) };
            let storage = this.storage.as_ref().unwrap();
            // One message, one WriteFile, never partial-write retries. All referenced
            // storage is heap-stable before submission; NULL byte count for overlapped I/O.
            if unsafe { WriteFile(storage.pipe.as_raw_handle(), storage.frame.as_ptr(), 36,
                null_mut(), storage.operation.get()) } != 0 { return Ok(this); }
            let error = io::Error::last_os_error();
            if error.raw_os_error() == Some(ERROR_IO_PENDING as i32) { return Ok(this); }
            // WriteFile rejected submission: no outstanding OVERLAPPED was established.
            this.storage.take();
            Err(error)
        }
        fn poll(&mut self) -> io::Result<Option<io::Result<()>>> {
            let storage = self.storage.as_ref().unwrap();
            let mut transferred = 0;
            if unsafe { GetOverlappedResult(storage.pipe.as_raw_handle(), storage.operation.get(), &mut transferred, 0) } != 0 {
                self.storage.take();
                return Ok(Some(require_frame_size(transferred)));
            }
            let error = io::Error::last_os_error();
            if error.raw_os_error() == Some(ERROR_IO_INCOMPLETE as i32) { return Ok(None); }
            if error.raw_os_error() == Some(ERROR_OPERATION_ABORTED as i32) {
                self.storage.take();
                return Ok(Some(Err(error)));
            }
            // An unexpected query failure does not prove that kernel ownership ended.
            Err(error)
        }
        fn cancel(&self) -> io::Result<()> {
            let storage = self.storage.as_ref().unwrap();
            if unsafe { CancelIoEx(storage.pipe.as_raw_handle(), storage.operation.get()) } != 0 { return Ok(()); }
            let error = io::Error::last_os_error();
            // NOT_FOUND is not a completion result either. Storage stays retained.
            if error.raw_os_error() == Some(ERROR_NOT_FOUND as i32) { return Ok(()); }
            Err(error)
        }
    }
    impl Drop for PendingStopWrite {
        fn drop(&mut self) {
            if self.storage.is_some() {
                let _ = self.cancel();
                std::mem::forget(self.storage.take());
            }
        }
    }

    #[cfg(test)]
    mod recovery_contract_tests {
        use super::{require_complete_record, require_frame_size, require_launch_identity, AcquisitionStage, FileIdentity};
        use super::super::super::windows_record::Record;

        #[test]
        fn acquisition_context_preserves_native_source_and_kind() {
            let original = std::io::Error::from_raw_os_error(87);
            let kind = original.kind();
            let message = original.to_string();
            let error = AcquisitionStage::ProcessOpen.error(original);
            assert_eq!(error.kind(), kind);
            assert_eq!(error.raw_os_error(), None);
            let source = std::error::Error::source(&error).unwrap()
                .downcast_ref::<std::io::Error>().unwrap();
            assert_eq!(source.raw_os_error(), Some(87));
            assert_eq!(source.kind(), kind);
            assert_eq!(source.to_string(), message);
            assert_eq!(error.to_string(), format!("open recorded process (OpenProcess): {message}"));
        }

        #[test]
        fn acquisition_context_labels_are_fixed_and_non_secret() {
            let stages = [
                (AcquisitionStage::RecordAncestry, "validate record ancestry"),
                (AcquisitionStage::RecordName, "encode record name"),
                (AcquisitionStage::RecordOpen, "open record (CreateFileW)"),
                (AcquisitionStage::RecordValidation, "validate opened record (security, contents and file identity)"),
                (AcquisitionStage::ProcessOpen, "open recorded process (OpenProcess)"),
                (AcquisitionStage::ProcessAdmission, "check recorded process identity and liveness"),
            ];
            // Synthetic only: no record/path is accepted by the contextualizer.
            let private_path = r"C:\private-synthetic-profile\daemon.pid";
            let capability = "synthetic-private-capability-0123456789";
            for (stage, label) in stages {
                let original = std::io::Error::from_raw_os_error(87);
                let message = original.to_string();
                let error = stage.error(original);
                let displayed = error.to_string();
                assert_eq!(displayed, format!("{label}: {message}"));
                assert!(!displayed.contains(private_path));
                assert!(!displayed.contains(capability));
                let debug = format!("{error:?}");
                assert!(!debug.contains(private_path));
                assert!(!debug.contains(capability));
            }
        }

        #[test]
        fn acquisition_context_preserves_non_native_validation_failure() {
            let error = AcquisitionStage::RecordValidation.error(std::io::Error::new(
                std::io::ErrorKind::InvalidData, "synthetic unsafe provenance"));
            assert_eq!(error.kind(), std::io::ErrorKind::InvalidData);
            let source = std::error::Error::source(&error).unwrap()
                .downcast_ref::<std::io::Error>().unwrap();
            assert_eq!(source.kind(), std::io::ErrorKind::InvalidData);
            assert_eq!(source.raw_os_error(), None);
            assert_eq!(source.to_string(), "synthetic unsafe provenance");
        }
        #[test]
        fn deletion_requires_full_file_and_full_launch_identity() {
            let identity = FileIdentity { volume: 7, id: [8; 16], created: 9 };
            let expected = Record::new(42, 123, [1; 16], [2; 32]).unwrap();
            assert!(require_complete_record(identity, &expected, identity, &expected).is_ok());
            for changed in [FileIdentity { volume: 10, ..identity },
                FileIdentity { id: [11; 16], ..identity }, FileIdentity { created: 12, ..identity }] {
                assert!(require_complete_record(identity, &expected, changed, &expected).is_err());
            }
            for changed in [Record::new(43, 123, [1; 16], [2; 32]).unwrap(),
                Record::new(42, 124, [1; 16], [2; 32]).unwrap(),
                Record::new(42, 123, [3; 16], [2; 32]).unwrap(),
                Record::new(42, 123, [1; 16], [4; 32]).unwrap()] {
                assert!(require_complete_record(identity, &expected, identity, &changed).is_err());
            }
        }
        #[test]
        fn pid_reuse_or_creation_mismatch_is_not_exact_identity() {
            assert!(require_launch_identity(42, 123, 42, 123).is_ok());
            assert!(require_launch_identity(42, 123, 43, 123).is_err());
            assert!(require_launch_identity(42, 123, 42, 124).is_err());
        }
        #[test]
        fn only_a_complete_single_frame_is_accepted() {
            assert!(require_frame_size(36).is_ok());
            for count in [0, 1, 35, 37, u32::MAX] { assert!(require_frame_size(count).is_err()); }
        }
    }

    struct Descriptor(*mut std::ffi::c_void);
    impl Descriptor {
        fn for_user(sid: PSID) -> io::Result<Self> {
            let mut text = null_mut();
            unsafe { checked(ConvertSidToStringSidW(sid, &mut text))?; }
            let _text_owner = SecuritySnapshot(text.cast());
            let mut length = 0;
            while length < 512 && unsafe { *text.add(length) } != 0 { length += 1; }
            if length == 512 { return Err(unsafe_record()); }
            let user = String::from_utf16(unsafe { std::slice::from_raw_parts(text, length) }).map_err(|_| unsafe_record())?;
            let sddl = wide(std::ffi::OsStr::new(&format!("O:{user}D:P(A;;FA;;;{user})")))?;
            let mut descriptor = null_mut();
            unsafe { checked(ConvertStringSecurityDescriptorToSecurityDescriptorW(sddl.as_ptr(), SDDL_REVISION_1,
                &mut descriptor, null_mut()))?; }
            Ok(Self(descriptor))
        }
        fn attributes(&self) -> SECURITY_ATTRIBUTES {
            SECURITY_ATTRIBUTES { nLength: std::mem::size_of::<SECURITY_ATTRIBUTES>() as u32,
                lpSecurityDescriptor: self.0, bInheritHandle: 0 }
        }
        fn dacl(&self) -> io::Result<*mut ACL> {
            let mut present = 0;
            let mut defaulted = 0;
            let mut dacl = null_mut();
            unsafe { checked(GetSecurityDescriptorDacl(self.0, &mut present, &mut dacl, &mut defaulted))?; }
            if present == 0 || dacl.is_null() { return Err(io::Error::other("private file ACL missing")); }
            Ok(dacl)
        }
    }
    impl Drop for Descriptor { fn drop(&mut self) { unsafe { LocalFree(self.0) }; } }
    fn private_file(path: &Path, access: u32, disposition: u32, descriptor: &Descriptor) -> io::Result<File> {
        let name = wide(path.as_os_str())?;
        let attributes = descriptor.attributes();
        let handle = owned(unsafe { CreateFileW(name.as_ptr(), access | READ_CONTROL | WRITE_DAC,
            FILE_SHARE_READ | FILE_SHARE_WRITE, &attributes, disposition,
            FILE_ATTRIBUTE_NORMAL | FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) })?;
        let mut info: BY_HANDLE_FILE_INFORMATION = unsafe { std::mem::zeroed() };
        unsafe { checked(GetFileInformationByHandle(handle.as_raw_handle(), &mut info))?; }
        if info.dwFileAttributes & (FILE_ATTRIBUTE_DIRECTORY | FILE_ATTRIBUTE_REPARSE_POINT) != 0 {
            return Err(io::Error::other("private daemon file must be regular and not a reparse point"));
        }
        let result = unsafe { SetSecurityInfo(handle.as_raw_handle(), SE_FILE_OBJECT,
            DACL_SECURITY_INFORMATION | PROTECTED_DACL_SECURITY_INFORMATION,
            null_mut(), null_mut(), descriptor.dacl()?, null_mut()) };
        if result != ERROR_SUCCESS { return Err(io::Error::from_raw_os_error(result as i32)); }
        Ok(File::from(handle))
    }
    /// The daemon itself opens this directory by path (its token, config and logs), without
    /// an inherited handle. An OWNER RIGHTS entry would follow the owner, which is the
    /// Administrators group when an elevated app created it, and then shut out the same
    /// user unelevated. Both the directory and the log name the user's SID instead.
    pub(crate) fn open_private_log(data_dir: &Path) -> io::Result<File> {
        let sid = current_user_sid()?;
        let descriptor = Descriptor::for_user(sid.as_ptr() as PSID)?;
        if let Some(parent) = data_dir.parent().filter(|path| !path.as_os_str().is_empty()) { std::fs::create_dir_all(parent)?; }
        let name = wide(data_dir.as_os_str())?;
        let attributes = descriptor.attributes();
        if unsafe { CreateDirectoryW(name.as_ptr(), &attributes) } == 0 {
            let error = io::Error::last_os_error();
            if error.raw_os_error() != Some(ERROR_ALREADY_EXISTS as i32) { return Err(error); }
        }
        // Repair the exact directory handle, not a path checked earlier. Omitting share-delete
        // keeps it from being renamed/replaced while the private log is opened beneath it.
        let directory = owned(unsafe { CreateFileW(name.as_ptr(), READ_CONTROL | WRITE_DAC,
            FILE_SHARE_READ | FILE_SHARE_WRITE, null(), OPEN_EXISTING,
            FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) })?;
        let mut info: BY_HANDLE_FILE_INFORMATION = unsafe { std::mem::zeroed() };
        unsafe { checked(GetFileInformationByHandle(directory.as_raw_handle(), &mut info))?; }
        if info.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY == 0 || info.dwFileAttributes & FILE_ATTRIBUTE_REPARSE_POINT != 0 {
            return Err(io::Error::other("private daemon directory must not be a reparse point"));
        }
        let result = unsafe { SetSecurityInfo(directory.as_raw_handle(), SE_FILE_OBJECT,
            DACL_SECURITY_INFORMATION | PROTECTED_DACL_SECURITY_INFORMATION,
            null_mut(), null_mut(), descriptor.dacl()?, null_mut()) };
        if result != ERROR_SUCCESS { return Err(io::Error::from_raw_os_error(result as i32)); }
        private_file(&data_dir.join("daemon.log"), FILE_APPEND_DATA | SYNCHRONIZE, OPEN_ALWAYS, &descriptor)
    }
    struct OwnedRecord {
        expected: super::super::windows_record::Record,
        identity: Option<FileIdentity>,
        path: PathBuf,
        file: Option<File>,
        _ancestry: Vec<OwnedHandle>,
        deletion_marked: bool,
    }
    impl WindowsChild {
        fn publish_record(&mut self, data_dir: &Path) -> io::Result<()> {
            use super::super::windows_record::Record;
            use std::io::Write;
            let mut random = [0u8; 48];
            getrandom::fill(&mut random).map_err(|_| recovery_error("launch record randomness unavailable"))?;
            let expected = Record::new(self.pid, self.started_owned()?,
                random[..16].try_into().unwrap(), random[16..].try_into().unwrap())?;
            let path = data_dir.join(super::super::PID_FILE);
            let ancestry = record_ancestry(&path, false)?;
            let sid = current_user_sid()?;
            let descriptor = Descriptor::for_user(sid.as_ptr() as PSID)?;
            let name = wide(path.as_os_str())?;
            let file = File::from(owned(unsafe { CreateFileW(name.as_ptr(), GENERIC_READ | GENERIC_WRITE | READ_CONTROL,
                FILE_SHARE_READ, &descriptor.attributes(), CREATE_NEW,
                FILE_ATTRIBUTE_NORMAL | FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) })?);
            // Install before any information/write/flush query can fail. Never overwrite
            // an unresolved record, nor discard ownership of a partially written one.
            self.record = Some(OwnedRecord { expected, identity: None, path, file: Some(file),
                _ancestry: ancestry, deletion_marked: false });
            let record = self.record.as_mut().unwrap();
            let file = record.file.as_mut().unwrap();
            let info = file_info(file.as_raw_handle())?;
            record.identity = Some(FileIdentity::from_handle(file.as_raw_handle(), &info)?);
            file.write_all(&record.expected.encode())?;
            file.sync_all()?;
            // A writer must not survive ResumeThread: addon opens with FILE_SHARE_READ.
            drop(record.file.take());
            let raw = unsafe { CreateFileW(name.as_ptr(), GENERIC_READ | READ_CONTROL, FILE_SHARE_READ,
                null(), OPEN_EXISTING, FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) };
            record.file = Some(File::from(owned(raw)?));
            let (observed, identity) = read_record_file(record.file.as_mut().unwrap())?;
            require_complete_record(record.identity.ok_or_else(unsafe_record)?, &record.expected, identity, &observed)

        }
        fn finish_record(&mut self) -> io::Result<()> {
            if self.record.is_none() { return Ok(()); }
            // Only this retained created-process/Job owner may retire a forced exit.
            // RecoveredLaunch::delete_record still requires its separate clean exit.
            if !self.completed || self.status()?.is_none() || self.query()? != 0 {
                return Err(recovery_error("owned Windows root/Job completion is unconfirmed; record retained"));
            }
            let pid = unsafe { GetProcessId(self.process.as_raw_handle()) };
            if pid == 0 { return Err(io::Error::last_os_error()); }
            let created = self.started_owned()?;
            let record = self.record.as_mut().unwrap();
            require_launch_identity(record.expected.pid, record.expected.created, pid, created)?;
            let identity = record.identity.ok_or_else(|| recovery_error("published Windows file identity is unconfirmed"))?;
            delete_exact_record(&record.path, &record.expected, identity, &mut record.file, &mut record.deletion_marked)
        }
    }

    fn delete_exact_record(path: &Path, expected: &super::super::windows_record::Record,
        identity: FileIdentity, guard: &mut Option<File>, marked: &mut bool) -> io::Result<()> {
        let name = wide(path.as_os_str())?;
        if !*marked {
            // Callers retain ancestry and checked exact-process completion throughout.
            // The old reader disallows DELETE; close only that guard before reopening.
            drop(guard.take());
            let raw = unsafe { CreateFileW(name.as_ptr(), GENERIC_READ | READ_CONTROL | DELETE,
                FILE_SHARE_READ, null(), OPEN_EXISTING, FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) };
            *guard = Some(File::from(owned(raw)?));
            let file = guard.as_mut().unwrap();
            let (observed, observed_identity) = read_record_file(file)?;
            require_complete_record(identity, expected, observed_identity, &observed)?;
            let disposition = FILE_DISPOSITION_INFO { DeleteFile: true };
            unsafe { checked(SetFileInformationByHandle(file.as_raw_handle(), FileDispositionInfo,
                (&disposition as *const FILE_DISPOSITION_INFO).cast(), std::mem::size_of_val(&disposition) as u32))?; }
            *marked = true;
            drop(guard.take());
        }
        // Mark-for-delete alone is not reclamation: another reader may defer deletion.
        // Only absence confirms retirement. Once marked, never delete a path replacement.
        let raw = unsafe { CreateFileW(name.as_ptr(), FILE_READ_ATTRIBUTES, FILE_SHARE_READ,
            null(), OPEN_EXISTING, FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) };
        if raw == INVALID_HANDLE_VALUE {
            let error = io::Error::last_os_error();
            if error.raw_os_error() == Some(ERROR_FILE_NOT_FOUND as i32) { return Ok(()); }
            return Err(error);
        }
        drop(owned(raw)?);
        Err(recovery_error("Windows launch record deletion/absence is not confirmed"))
    }

    #[cfg(test)]
    mod recovered_io_tests {
        use super::*;
        use super::super::super::windows_record::Record;
        use std::io::{BufRead, BufReader, Write};
        use std::process::{Child, Command, Stdio};
        use std::sync::mpsc;

        const TEST_WAIT: Duration = Duration::from_secs(20);

        // Open through the real production worker with a generous scheduling budget,
        // then requeue its exact native result before testing a shorter stop deadline.
        fn ready_connection(fixture: &Fixture) -> ConnectAttempt {
            let name = wide(std::ffi::OsStr::new(&fixture.record.pipe_name())).unwrap();
            let mut connect = ConnectAttempt::start(name, Instant::now() + TEST_WAIT).unwrap();
            let pipe = connect.result.recv_timeout(TEST_WAIT).expect("stop worker did not connect").unwrap();
            let (sender, receiver) = mpsc::channel();
            sender.send(Ok(pipe)).unwrap();
            connect.result = receiver;
            connect
        }

        // Every panic path kills the helper. No wait()/reader join can hang the test.
        struct PipeHost(Child);
        impl PipeHost {
            fn exit(&mut self) -> std::process::ExitStatus {
                let deadline = Instant::now() + TEST_WAIT;
                loop {
                    if let Some(status) = self.0.try_wait().unwrap() { return status; }
                    assert!(Instant::now() < deadline, "foreign pipe host did not exit");
                    std::thread::sleep(RECOVERY_POLL);
                }
            }
        }
        impl Drop for PipeHost {
            fn drop(&mut self) { let _ = self.0.kill(); }
        }

        struct Fixture { dir: PathBuf, record: Record }
        impl Fixture {
            fn new() -> Self {
                let mut random = [0u8; 48];
                getrandom::fill(&mut random).unwrap();
                let mut created: FILETIME = unsafe { std::mem::zeroed() };
                let mut exited = created; let mut kernel = created; let mut user = created;
                unsafe { checked(GetProcessTimes(GetCurrentProcess(), &mut created, &mut exited,
                    &mut kernel, &mut user)).unwrap(); }
                let record = Record::new(std::process::id(),
                    ((created.dwHighDateTime as u64) << 32) | created.dwLowDateTime as u64,
                    random[..16].try_into().unwrap(), random[16..].try_into().unwrap()).unwrap();
                let dir = std::env::temp_dir().join(format!("gd-recovery-{:032x}",
                    u128::from_le_bytes(random[..16].try_into().unwrap())));
                ensure_record_directory(&dir).unwrap();
                let fixture = Self { dir, record };
                fixture.write_record(&fixture.record);
                fixture
            }
            fn path(&self) -> PathBuf { self.dir.join(super::super::super::PID_FILE) }
            fn write_record(&self, record: &Record) {
                let sid = current_user_sid().unwrap();
                let descriptor = Descriptor::for_user(sid.as_ptr() as PSID).unwrap();
                let name = wide(self.path().as_os_str()).unwrap();
                let mut file = File::from(owned(unsafe { CreateFileW(name.as_ptr(), GENERIC_WRITE,
                    0, &descriptor.attributes(), CREATE_NEW, FILE_ATTRIBUTE_NORMAL, null_mut()) }).unwrap());
                file.write_all(&record.encode()).unwrap();
                file.sync_all().unwrap();
            }
            fn owner(&self) -> RecoveredLaunch {
                match acquire_recovered_launch(&self.dir) {
                    Ok(Some(owner)) => owner,
                    _ => panic!("fixture's exact live process must be admitted"),
                }
            }
            fn server(&self) -> OwnedHandle {
                let name = wide(std::ffi::OsStr::new(&self.record.pipe_name())).unwrap();
                let sid = current_user_sid().unwrap();
                let descriptor = Descriptor::for_user(sid.as_ptr() as PSID).unwrap();
                owned(unsafe { CreateNamedPipeW(name.as_ptr(), PIPE_ACCESS_INBOUND | FILE_FLAG_FIRST_PIPE_INSTANCE,
                    PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE | PIPE_WAIT | PIPE_REJECT_REMOTE_CLIENTS,
                    1, 4096, 4096, 0, &descriptor.attributes()) }).unwrap()
            }
        }
        impl Drop for Fixture {
            fn drop(&mut self) { let _ = std::fs::remove_dir_all(&self.dir); }
        }

        fn connected_client(fixture: &Fixture, server: &OwnedHandle) -> OwnedHandle {
            let name = wide(std::ffi::OsStr::new(&fixture.record.pipe_name())).unwrap();
            let client = owned(unsafe { CreateFileW(name.as_ptr(), FILE_WRITE_DATA, 0, null(), OPEN_EXISTING,
                FILE_FLAG_OVERLAPPED | SECURITY_SQOS_PRESENT | SECURITY_IDENTIFICATION, null_mut()) }).unwrap();
            let result = unsafe { ConnectNamedPipe(server.as_raw_handle(), null_mut()) };
            assert!(result != 0 || io::Error::last_os_error().raw_os_error() == Some(ERROR_PIPE_CONNECTED as i32));
            client
        }

        #[test]
        fn stop_deadline_and_cancellation_retain_pending_write_storage() {
            let fixture = Fixture::new();
            let server = fixture.server();
            let client = connected_client(&fixture, &server);
            let mut owner = fixture.owner();
            // Fill the real pipe's quota without a reader. Never rely on a specific
            // Windows minimum quota or on the first write completing synchronously.
            let fill_deadline = Instant::now() + TEST_WAIT;
            let pending = loop {
                assert!(Instant::now() < fill_deadline, "pipe quota did not become bounded backpressure");
                // A non-inheritable test-only duplicate lets each completed write
                // release its own handle without disconnecting the quota-fill client.
                let mut write = PendingStopWrite::submit(client.try_clone().unwrap(), fixture.record.frame()).unwrap();
                let probe_deadline = Instant::now() + Duration::from_millis(30);
                loop {
                    match write.poll().unwrap() {
                        Some(result) => { result.unwrap(); break; }
                        None if Instant::now() >= probe_deadline => break,
                        None => std::thread::sleep(Duration::from_millis(1)),
                    }
                }
                if write.storage.is_some() { break write; }
            };
            drop(client);
            owner.attempted = true;
            owner.write = Some(pending);
            let allocation = owner.write.as_ref().unwrap().storage.as_ref().unwrap().operation.get();
            let started = Instant::now();
            assert_eq!(owner.stop(Duration::from_millis(40)).unwrap_err().kind(), io::ErrorKind::TimedOut);
            assert!(started.elapsed() < TEST_WAIT, "stop ignored its bounded deadline");
            // CancelIoEx is only a request: even an already-completed cancellation
            // must not free kernel-referenced memory until poll observes completion.
            assert_eq!(owner.write.as_ref().unwrap().storage.as_ref().unwrap().operation.get(), allocation);
            owner.write.as_ref().unwrap().cancel().unwrap();
            assert_eq!(owner.write.as_ref().unwrap().storage.as_ref().unwrap().operation.get(), allocation);
            let completion_deadline = Instant::now() + TEST_WAIT;
            loop {
                if let Some(result) = owner.write.as_mut().unwrap().poll().unwrap() {
                    assert_eq!(result.unwrap_err().raw_os_error(), Some(ERROR_OPERATION_ABORTED as i32));
                    owner.write.take();
                    break;
                }
                assert!(Instant::now() < completion_deadline, "cancelled write did not settle");
                std::thread::sleep(Duration::from_millis(1));
            }
            assert!(owner.stop(Duration::from_millis(40)).is_err());
            assert!(owner.attempted && !owner.written);
            assert!(owner.connect.is_none() && owner.write.is_none());
            assert!(owner.record.is_some() && owner.process.is_some());
            assert!(owner.delete_record().is_err());
        }

        #[test]
        fn recovered_stop_sends_one_authenticated_frame_and_retains_timeout_state() {
            let fixture = Fixture::new();
            let server = fixture.server();
            let mut owner = fixture.owner();
            owner.connect = Some(ready_connection(&fixture));
            // The real worker has already delivered its connection, so scheduling it
            // cannot consume the two-second budget being tested below.
            // The pipe server is this exact recorded process. It deliberately stays
            // alive after receiving the authenticated frame, forcing a retained error.
            assert_eq!(owner.stop(Duration::from_secs(2)).unwrap_err().kind(), io::ErrorKind::TimedOut);
            assert!(owner.attempted && owner.written);
            assert_eq!(owner.stop(Duration::from_millis(40)).unwrap_err().kind(), io::ErrorKind::TimedOut);
            let mut available = 0;
            unsafe { checked(PeekNamedPipe(server.as_raw_handle(), null_mut(), 0, null_mut(),
                &mut available, null_mut())).unwrap(); }
            assert_eq!(available, 36, "a retry sent another authenticated frame");
            let mut frame = [0u8; 36];
            let mut read = 0;
            unsafe { checked(ReadFile(server.as_raw_handle(), frame.as_mut_ptr(), 36, &mut read, null_mut())).unwrap(); }
            assert_eq!(read, 36);
            assert_eq!(frame, fixture.record.frame());
            assert!(owner.record.is_some() && owner.process.is_some());
            assert!(owner.connect.is_none() && owner.write.is_none());
            assert!(owner.delete_record().is_err());
            assert!(fixture.path().exists());
        }

        #[test]
        fn recovered_stop_refuses_foreign_pipe_server_without_sending_frame() {
            let fixture = Fixture::new();
            let full_name = fixture.record.pipe_name();
            let bare_name = full_name.strip_prefix(r"\\.\pipe\").unwrap();
            // Only a generated lowercase-hex nonce enters this PowerShell literal.
            assert!(bare_name.strip_prefix("gentle-dot-stop-").unwrap()
                .bytes().all(|byte| byte.is_ascii_hexdigit()));
            let script = format!(r#"
$ErrorActionPreference = 'Stop'
$pipe = [System.IO.Pipes.NamedPipeServerStream]::new(
    '{bare_name}', [System.IO.Pipes.PipeDirection]::InOut, 1,
    [System.IO.Pipes.PipeTransmissionMode]::Byte,
    [System.IO.Pipes.PipeOptions]::Asynchronous)
try {{
    # Wait for a connection before announcing readiness: the refused client may
    # connect and close at once, before a later wait could begin.
    $connect = $pipe.WaitForConnectionAsync()
    [Console]::WriteLine('READY')
    if (-not $connect.Wait(20000)) {{ throw 'connection timeout' }}
    $buffer = New-Object byte[] 256
    $total = 0
    $timer = [System.Diagnostics.Stopwatch]::StartNew()
    # The refused client closes its end: a broken pipe ends the read like EOF does.
    try {{
        while ($timer.ElapsedMilliseconds -lt 20000) {{
            $read = $pipe.ReadAsync($buffer, 0, $buffer.Length)
            if (-not $read.Wait([int][Math]::Max(1, 20000 - $timer.ElapsedMilliseconds))) {{ break }}
            $count = $read.Result
            if ($count -eq 0) {{ break }}
            $total += $count
        }}
    }} catch {{ }}
    [Console]::WriteLine('BYTES:' + $total)
}} catch {{
    # Surface the host's failure in the test's assertion instead of losing it with stderr.
    [Console]::WriteLine('ERR:' + ($_.Exception.ToString() -replace '\s+', ' '))
}} finally {{ $pipe.Dispose() }}
"#);
            let system_root = std::env::var_os("SystemRoot").expect("Windows system directory missing");
            let powershell = PathBuf::from(system_root)
                .join(r"System32\WindowsPowerShell\v1.0\powershell.exe");
            let mut host = PipeHost(Command::new(powershell)
                .args(["-NoProfile", "-Command", &script])
                .stdin(Stdio::null()).stdout(Stdio::piped()).stderr(Stdio::null())
                .spawn().expect("start foreign same-user pipe host"));
            assert_ne!(host.0.id(), fixture.record.pid);
            let stdout = host.0.stdout.take().unwrap();
            let (sender, lines) = mpsc::channel();
            // A blocking pipe read lives only on this observer; recv_timeout bounds
            // the controller, and PipeHost kills Q on every failure path.
            let _reader = std::thread::spawn(move || {
                for line in BufReader::new(stdout).lines() {
                    if sender.send(line).is_err() { break; }
                }
            });
            assert_eq!(lines.recv_timeout(TEST_WAIT).expect("foreign pipe readiness timed out").unwrap(), "READY");
            let mut owner = fixture.owner();
            owner.connect = Some(ready_connection(&fixture));
            let error = owner.stop(Duration::from_secs(2)).unwrap_err();
            assert_eq!(error.kind(), io::ErrorKind::Other);
            assert_eq!(error.to_string(), "Windows stop pipe server identity does not match");
            assert!(!owner.attempted && !owner.written);
            assert!(owner.connect.is_none() && owner.write.is_none());
            assert!(owner.record.is_some() && owner.process.is_some());
            assert_eq!(lines.recv_timeout(TEST_WAIT).expect("foreign pipe byte count timed out").unwrap(), "BYTES:0");
            assert!(host.exit().success());
            assert!(owner.delete_record().is_err());
            assert!(fixture.path().exists());
        }

        #[test]
        fn exact_deletion_refuses_replaced_file_and_changed_launch_identity() {
            let fixture = Fixture::new();
            let mut validated = read_validated_record(&fixture.dir).unwrap().unwrap();
            let identity = validated.identity;
            drop(validated.file.take());
            // Keep the old file alive under another name, so the replacement cannot
            // reuse its file ID even on filesystems with aggressive ID reuse.
            std::fs::rename(fixture.path(), fixture.dir.join("old-record")).unwrap();
            fixture.write_record(&fixture.record);
            assert!(delete_exact_record(&validated.path, &fixture.record, identity,
                &mut validated.file, &mut validated.deletion_marked).is_err());
            assert!(!validated.deletion_marked);
            assert!(validated.file.is_some());
            drop(validated.file.take());
            let mut replacement = read_validated_record(&fixture.dir).unwrap().unwrap();
            let changed = Record::new(fixture.record.pid, fixture.record.created + 1,
                [3; 16], [4; 32]).unwrap();
            assert!(delete_exact_record(&replacement.path, &changed, replacement.identity,
                &mut replacement.file, &mut replacement.deletion_marked).is_err());
            assert!(!replacement.deletion_marked);
            assert!(replacement.file.is_some());
            assert!(fixture.path().exists());
            drop(replacement);
            drop(validated);
        }
    }

    #[cfg(test)]
    mod owner_exit_tests {
        use super::*;
        use super::super::super::{windows_record, Daemon, PID_FILE};
        use crate::app_channel::windows::channel_pair;
        use std::{fs, thread};
        use std::sync::{mpsc, Arc};

        // Owner-exit recovery runs the launching app in a child copy of this test binary, so
        // killing that exact child handle (never a PID lookup) closes the only Job handle.
        const OWNER_HELPER: &str = "daemon::windows::native::owner_exit_tests::recovery_owner_helper";
        const OWNER_HELPER_DIR: &str = "GENTLE_DOT_TEST_RECOVERY_OWNER_DIR";
        const OWNER_FILE: &str = "daemon.owner";

        #[test]
        #[ignore = "launching-app child for owner-exit recovery tests; returns at once without its environment"]
        fn recovery_owner_helper() {
            let Some(dir) = std::env::var_os(OWNER_HELPER_DIR) else { return };
            let dir = PathBuf::from(dir);
            let script = r#"
const {spawn} = require('node:child_process');
// Outlive the Node root while still inheriting the retained outer owned Job.
const child = spawn(process.execPath, ['-e', "process.stdout.write('CHILD_READY\\n');setTimeout(()=>{},60000)"],
  {stdio:['ignore','pipe','ignore'],windowsHide:true,detached:true});
child.stdout.once('data', bytes => {
  if (bytes.toString() !== 'CHILD_READY\n') process.exit(75);
  console.log('DESCENDANT ' + child.pid);
});
setTimeout(()=>process.exit(74),60000);
"#;
            let launch = LaunchSpec { program: env!("GENTLE_DOT_BUILD_NODE").into(),
                args: vec!["-e".into(), script.into()], envs: vec![("NODE_OPTIONS".into(), String::new())] };
            let (_parent, endpoint) = channel_pair().unwrap();
            let child = super::spawn(&launch, super::open_private_log(&dir).unwrap(), &endpoint, &dir).unwrap();
            drop(endpoint);
            println!("OWNER_READY {}", child.id());
            thread::sleep(Duration::from_secs(60));
        }

        struct OwnerRun {
            helper: std::process::Child,
            dir: PathBuf,
            root: std::os::windows::io::OwnedHandle,
            descendant: std::os::windows::io::OwnedHandle,
        }
        impl Drop for OwnerRun {
            fn drop(&mut self) { let _ = self.helper.kill(); let _ = self.helper.wait(); }
        }
        // Test witness only, opened while the fixture reports the process live.
        fn open_witness(pid: u32) -> std::os::windows::io::OwnedHandle {
            use std::os::windows::io::FromRawHandle;
            use windows_sys::Win32::System::Threading::{OpenProcess, PROCESS_QUERY_LIMITED_INFORMATION};
            let raw = unsafe { OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION
                | windows_sys::Win32::Storage::FileSystem::SYNCHRONIZE, 0, pid) };
            assert!(!raw.is_null(), "fixture process witness");
            unsafe { std::os::windows::io::OwnedHandle::from_raw_handle(raw) }
        }
        fn exits_within(process: &std::os::windows::io::OwnedHandle, millis: u32) -> bool {
            use std::os::windows::io::AsRawHandle;
            let result = unsafe { windows_sys::Win32::System::Threading::WaitForSingleObject(process.as_raw_handle(), millis) };
            result == windows_sys::Win32::Foundation::WAIT_OBJECT_0
        }
        fn start_owner(name: &str) -> OwnerRun {
            let mut nonce = [0u8; 8];
            getrandom::fill(&mut nonce).unwrap();
            let token: String = nonce.iter().map(|b| format!("{b:02x}")).collect();
            let dir = std::env::temp_dir().join(format!("gentle-owner-{name}-{token}"));
            super::ensure_record_directory(&dir).unwrap();
            let mut helper = std::process::Command::new(std::env::current_exe().unwrap())
                .args([OWNER_HELPER, "--exact", "--ignored", "--nocapture", "--test-threads=1"])
                .env(OWNER_HELPER_DIR, &dir)
                .stdin(std::process::Stdio::null()).stdout(std::process::Stdio::piped())
                .stderr(std::process::Stdio::null()).spawn().unwrap();
            let stdout = helper.stdout.take().unwrap();
            let (lines, ready) = mpsc::channel();
            thread::spawn(move || {
                for line in io::BufRead::lines(io::BufReader::new(stdout)).map_while(Result::ok) {
                    if lines.send(line).is_err() { break; }
                }
            });
            let root: u32 = loop {
                let line = ready.recv_timeout(Duration::from_secs(30)).expect("owner helper readiness");
                // libtest prints `test <name> ... ` without a newline before the helper's output.
                if let Some((_, pid)) = line.split_once("OWNER_READY ") { break pid.trim().parse().unwrap(); }
            };
            let deadline = Instant::now() + Duration::from_secs(10);
            let descendant: u32 = loop {
                let log = fs::read_to_string(dir.join("daemon.log")).unwrap_or_default();
                if let Some(pid) = log.lines().find_map(|line| line.strip_prefix("DESCENDANT ")) {
                    break pid.trim().parse().unwrap();
                }
                assert!(Instant::now() < deadline, "fixture descendant readiness: {log}");
                thread::sleep(Duration::from_millis(20));
            };
            OwnerRun { root: open_witness(root), descendant: open_witness(descendant), helper, dir }
        }
        fn kill_owner(run: &mut OwnerRun) {
            run.helper.kill().unwrap();
            run.helper.wait().unwrap();
        }
        fn recovering_daemon(dir: &Path) -> Daemon {
            let mut daemon = Daemon::new(1, dir.to_path_buf(), None);
            daemon.health = Some(Arc::new(|| false));
            daemon
        }
        struct Sentinel(std::process::Child);
        impl Drop for Sentinel {
            fn drop(&mut self) { let _ = self.0.kill(); let _ = self.0.wait(); }
        }

        #[test]
        fn owner_exit_retires_record_after_kernel_ends_owned_group() {
            use std::os::windows::process::CommandExt;
            // Same executable, independently launched: never part of the owned Job.
            let mut sentinel = Sentinel(std::process::Command::new(env!("GENTLE_DOT_BUILD_NODE"))
                .args(["-e", "setTimeout(()=>{},60000)"]).env_remove("NODE_OPTIONS")
                .creation_flags(windows_sys::Win32::System::Threading::CREATE_NO_WINDOW)
                .stdin(std::process::Stdio::null()).stdout(std::process::Stdio::null())
                .stderr(std::process::Stdio::null()).spawn().unwrap());
            let mut run = start_owner("exit");
            let record = fs::read(run.dir.join(PID_FILE)).unwrap();
            let witness = fs::read(run.dir.join(OWNER_FILE)).unwrap();
            // Guards: a live witnessed owner refuses retirement; only its exit plus root
            // exit permits exact deletion. Removing the live-owner check must fail here.
            let live = recovering_daemon(&run.dir);
            let error = live.windows_recovery_admission(&None).unwrap_err();
            assert_eq!(error, "Windows previous launch admission refused: \
                the previous launch's owning app is still running; record retained");
            assert_eq!(live.refusal(), Some(error));
            assert_eq!(fs::read(run.dir.join(PID_FILE)).unwrap(), record);
            assert_eq!(fs::read(run.dir.join(OWNER_FILE)).unwrap(), witness);
            assert!(!exits_within(&run.root, 0) && !exits_within(&run.descendant, 0), "nothing was stopped");
            drop(live);
            kill_owner(&mut run);
            let daemon = recovering_daemon(&run.dir);
            assert_eq!(daemon.windows_recovery_admission(&None), Ok(()));
            assert_eq!(daemon.refusal(), None);
            assert!(!run.dir.join(PID_FILE).exists(), "exact record retired");
            assert!(exits_within(&run.root, 0), "retirement waits for the recorded root");
            assert!(exits_within(&run.descendant, 5000), "the kernel ended the whole owned Job");
            assert_eq!(fs::read(run.dir.join(OWNER_FILE)).unwrap(), witness,
                "retirement leaves the witness without authority");
            assert!(!retire_if_owner_exited(&run.dir).unwrap(), "no record is a no-op");
            assert!(sentinel.0.try_wait().unwrap().is_none(), "same executable outside the Job survives");
        }

        #[test]
        fn record_without_owner_witness_is_not_retired_after_owner_exit() {
            // Guard: no witness returns Ok(false), not successful retirement or an error.
            let mut run = start_owner("legacy");
            let record = fs::read(run.dir.join(PID_FILE)).unwrap();
            fs::remove_file(run.dir.join(OWNER_FILE)).unwrap();
            assert!(!retire_if_owner_exited(&run.dir).unwrap(), "missing witness is a no-op even with a live root");
            assert!(run.dir.join(PID_FILE).exists());
            kill_owner(&mut run);
            assert!(exits_within(&run.root, 5000));
            assert!(!retire_if_owner_exited(&run.dir).unwrap(), "a legacy launch is not retired");
            assert_eq!(fs::read(run.dir.join(PID_FILE)).unwrap(), record,
                "legacy records still need authorized manual recovery");
            assert!(!run.dir.join(OWNER_FILE).exists());
            let daemon = recovering_daemon(&run.dir);
            let error = daemon.windows_recovery_admission(&None).unwrap_err();
            assert!(error.starts_with("Windows recorded launch admission refused:"), "{error}");
            assert_eq!(daemon.refusal(), Some(error));
            assert_eq!(fs::read(run.dir.join(PID_FILE)).unwrap(), record,
                "failed recovered admission retains the legacy record");
        }

        #[test]
        fn invalid_or_unbound_witness_refuses_and_retains_record() {
            // Guards: invalid witnesses fail closed; valid witnesses must bind this nonce.
            // Removing either refusal changes the asserted error or deletes the record.
            let mut run = start_owner("mismatch");
            let record = fs::read(run.dir.join(PID_FILE)).unwrap();
            let path = run.dir.join(OWNER_FILE);
            let witness = fs::read(&path).unwrap();
            // A damaged witness is not a legacy record: refuse rather than try the recovered stop.
            fs::write(&path, b"not an owner witness\n").unwrap();
            let daemon = recovering_daemon(&run.dir);
            let error = daemon.windows_recovery_admission(&None).unwrap_err();
            assert_eq!(error, "Windows previous launch admission refused: \
                Windows owner witness is invalid or unreadable; record retained");
            assert_eq!(daemon.refusal(), Some(error));
            assert_eq!(fs::read(run.dir.join(PID_FILE)).unwrap(), record);
            assert_eq!(fs::read(&path).unwrap(), b"not an owner witness\n");
            assert!(!exits_within(&run.root, 0) && !exits_within(&run.descendant, 0), "nothing was stopped");
            // A witness for another record proves nothing, even after this owner exits.
            let owner = windows_record::Owner::parse(&witness).unwrap();
            let unbound = windows_record::Owner::new([0x5a; 16], owner.pid, owner.created).unwrap().encode();
            fs::write(&path, &unbound).unwrap();
            kill_owner(&mut run);
            assert!(exits_within(&run.root, 5000));
            let daemon = recovering_daemon(&run.dir);
            let error = daemon.windows_recovery_admission(&None).unwrap_err();
            assert_eq!(error, "Windows previous launch admission refused: \
                Windows owner witness does not match the recorded launch; record retained");
            assert_eq!(daemon.refusal(), Some(error));
            assert_eq!(fs::read(run.dir.join(PID_FILE)).unwrap(), record);
            assert_eq!(fs::read(&path).unwrap(), unbound);
        }

        #[test]
        fn exited_witness_with_running_root_retains_record_and_refuses() {
            // Guard: owner exit alone is insufficient; a live root must time out, not retire.
            use std::os::windows::io::AsRawHandle;
            let run = start_owner("contradiction");
            let bytes = fs::read(run.dir.join(PID_FILE)).unwrap();
            let record = windows_record::Record::parse(&bytes).unwrap();
            // An exited process that never held the Job: its exit proves nothing about the root.
            let mut other = std::process::Command::new(env!("GENTLE_DOT_BUILD_NODE"))
                .args(["-e", ""]).env_remove("NODE_OPTIONS").stdin(std::process::Stdio::null())
                .stdout(std::process::Stdio::null()).stderr(std::process::Stdio::null()).spawn().unwrap();
            other.wait().unwrap();
            let mut created: windows_sys::Win32::Foundation::FILETIME = unsafe { std::mem::zeroed() };
            let (mut exited, mut kernel, mut user) = (created, created, created);
            assert_ne!(unsafe { windows_sys::Win32::System::Threading::GetProcessTimes(other.as_raw_handle(),
                &mut created, &mut exited, &mut kernel, &mut user) }, 0);
            let created = ((created.dwHighDateTime as u64) << 32) | created.dwLowDateTime as u64;
            let witness = windows_record::Owner::new(record.nonce(), other.id(), created).unwrap().encode();
            fs::write(run.dir.join(OWNER_FILE), &witness).unwrap();
            let daemon = recovering_daemon(&run.dir);
            let started = Instant::now();
            let error = daemon.windows_recovery_admission(&None).unwrap_err();
            assert_eq!(error, "Windows previous launch admission refused: \
                recorded Windows root is still running after its owner exited; record retained");
            assert_eq!(daemon.refusal(), Some(error));
            assert!(started.elapsed() >= Duration::from_secs(9), "bounded wait for the recorded root");
            assert_eq!(fs::read(run.dir.join(PID_FILE)).unwrap(), bytes);
            assert_eq!(fs::read(run.dir.join(OWNER_FILE)).unwrap(), witness);
            assert!(!exits_within(&run.root, 0) && !exits_within(&run.descendant, 0), "nothing was terminated");
        }
    }

    #[cfg(test)]
    mod launch_tests {
        use super::*;

        fn spec() -> LaunchSpec {
            LaunchSpec { program: std::env::current_exe().unwrap().to_str().unwrap().into(), args: vec![], envs: vec![] }
        }

        #[test]
        fn daemon_creation_suppresses_console_without_changing_ownership_flags() {
            assert_eq!(DAEMON_CREATION_FLAGS,
                CREATE_NO_WINDOW | CREATE_SUSPENDED | CREATE_UNICODE_ENVIRONMENT | EXTENDED_STARTUPINFO_PRESENT);
            assert_eq!(DAEMON_CREATION_FLAGS & (CREATE_NEW_CONSOLE | DETACHED_PROCESS), 0);
        }

        #[test]
        fn transfer_list_matches_fd3_bootstrap_and_excludes_parent_handles() {
            let (parent, child) = crate::app_channel::windows::channel_pair().unwrap();
            let log = File::open(std::env::current_exe().unwrap()).unwrap();
            let transfers = Transfers::new(&log, &child).unwrap();
            let handles = transfers.handles();
            assert_eq!(handles.len(), 4);
            assert!(!handles.contains(&child.as_raw_handle()));
            let bytes = transfers.bootstrap().unwrap();
            assert_eq!(&bytes[4..8], &[65, 1, 1, 9]);
            for (index, handle) in handles.iter().enumerate() {
                let start = 8 + index * std::mem::size_of::<usize>();
                assert_eq!(&bytes[start..start + std::mem::size_of::<usize>()], &(*handle as usize).to_ne_bytes());
            }
            for handle in handles {
                let mut flags = 0;
                assert_ne!(unsafe { GetHandleInformation(handle, &mut flags) }, 0);
                assert_ne!(flags & HANDLE_FLAG_INHERIT, 0);
            }
            parent.shutdown().unwrap();
        }

        #[test]
        fn application_ignores_relative_and_empty_path_entries() {
            // cargo runs tests from the crate directory; target/ is ignored by git.
            let relative = PathBuf::from(format!(r"target\gd-relative-path-{}", std::process::id()));
            let absolute = std::env::temp_dir().join(format!("gd-absolute-path-{}", std::process::id()));
            for dir in [&relative, &absolute] {
                std::fs::create_dir_all(dir).unwrap();
                std::fs::write(dir.join("gd-probe-tool.exe"), b"").unwrap();
            }
            let spec = |path: String| LaunchSpec {
                program: "gd-probe-tool".into(),
                args: Vec::new(),
                envs: vec![("PATH".into(), path)],
            };
            let found = |path: String| application(&spec(path))
                .map(|wide| String::from_utf16(&wide[..wide.len() - 1]).unwrap());
            let only_relative = format!(";.;{}", relative.display());
            assert_eq!(found(only_relative).unwrap_err().kind(), io::ErrorKind::NotFound);
            let mixed = format!(";.;{};{}", relative.display(), absolute.display());
            let resolved = found(mixed).unwrap();
            assert!(resolved.ends_with(r"\gd-probe-tool.exe"));
            assert!(resolved.contains(&format!("gd-absolute-path-{}", std::process::id())));
            for dir in [&relative, &absolute] { let _ = std::fs::remove_dir_all(dir); }
        }

        #[test]
        fn private_log_directory_and_file_name_only_the_user() {
            // Owner and every DACL entry must be this user's SID, never OWNER RIGHTS: the
            // daemon reopens the directory by path, possibly unelevated (#128).
            let mut nonce = [0u8; 16];
            getrandom::fill(&mut nonce).unwrap();
            let token: String = nonce.iter().map(|b| format!("{b:02x}")).collect();
            let root = std::env::temp_dir().join(format!("gentle-private-log-{token}"));
            let log = open_private_log(&root).unwrap();
            let sid = current_user_sid().unwrap();
            validate_record_security(log.as_raw_handle(), sid.as_ptr() as PSID).expect("log names only the user");
            let name = wide(root.as_os_str()).unwrap();
            let directory = owned(unsafe { CreateFileW(name.as_ptr(), READ_CONTROL, FILE_SHARE_READ | FILE_SHARE_WRITE,
                null(), OPEN_EXISTING, FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT, null_mut()) }).unwrap();
            validate_record_security(directory.as_raw_handle(), sid.as_ptr() as PSID).expect("directory names only the user");
            // Reopening repairs, never loosens: the same check holds on the second call.
            drop(log);
            let log = open_private_log(&root).unwrap();
            validate_record_security(log.as_raw_handle(), sid.as_ptr() as PSID).unwrap();
            validate_record_security(directory.as_raw_handle(), sid.as_ptr() as PSID).unwrap();
        }

        #[test]
        fn retained_record_ancestry_blocks_renaming_an_ancestor() {
            let base = std::env::temp_dir().join(format!("gd-ancestry-pin-{}", std::process::id()));
            let _ = std::fs::remove_dir_all(&base);
            std::fs::create_dir_all(base.join(r"a\b")).unwrap();
            let held = record_ancestry(&base.join(r"a\b\daemon.pid"), false).unwrap();
            let renamed = base.join("a-renamed");
            let attempt = std::fs::rename(base.join("a"), &renamed);
            if attempt.is_ok() { let _ = std::fs::rename(&renamed, base.join("a")); }
            drop(held);
            let _ = std::fs::remove_dir_all(&base);
            assert!(attempt.is_err(), "an ancestor was renamed while the record ancestry was retained");
        }

        #[test]
        fn assignment_failure_never_resumes_and_cleans_owned_suspended_child() {
            let (parent, child) = crate::app_channel::windows::channel_pair().unwrap();
            let log = File::open(std::env::current_exe().unwrap()).unwrap();
            let failure = spawn_with_faults(&spec(), log, &child, Faults { assignment: true, ..Faults::default() }).unwrap_err();
            assert!(failure.primary.to_string().contains("injected assignment failure"));
            assert!(failure.unfinished.is_none());
            assert!(failure.cleanup.is_none());
            parent.shutdown().unwrap();
        }
        #[test]
        fn verification_failure_never_resumes_and_drains_owned_job() {
            let (parent, child) = crate::app_channel::windows::channel_pair().unwrap();
            let log = File::open(std::env::current_exe().unwrap()).unwrap();
            let failure = spawn_with_faults(&spec(), log, &child, Faults { verification: true, ..Faults::default() }).unwrap_err();
            assert!(failure.primary.to_string().contains("injected verification failure"));
            assert!(failure.unfinished.is_none());
            assert!(failure.cleanup.is_none());
            parent.shutdown().unwrap();
        }
        #[test]
        #[ignore = "explicit Windows checkout fd3 integration; synthetic processes and private record only"]
        fn production_fd3_drain_excludes_live_child_and_retires_owned_job() {
            use std::io::{Read, Write};
            let mut nonce = [0u8; 16];
            getrandom::fill(&mut nonce).unwrap();
            let token: String = nonce.iter().map(|b| format!("{b:02x}")).collect();
            let root = std::env::temp_dir().join(format!("gentle-fd3-integration-{token}"));
            ensure_record_directory(&root).unwrap();
            let log_path = root.join("daemon.log");
            let release = root.join("release");
            let adapter = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
                .join("../../../packages/daemon/src/windows-app-channel.ts");
            // Production TS entry and package-local addon; no injected loader,
            // daemon startup, secret store, installed agent, or model is involved.
            let script = r#"
import { pathToFileURL } from 'node:url';
import { win32 } from 'node:path';
import { existsSync } from 'node:fs';
import { spawn } from 'node:child_process';
import { once } from 'node:events';
const [adapter, release, token] = process.argv.slice(1);
const watchdog = setTimeout(() => { console.error('synthetic deadline'); process.exit(71); }, 20000);
const { WindowsAppChannel } = await import(pathToFileURL(adapter).href);
const { startWithWindowsStop } = await import(new URL('./windows-stop.ts', pathToFileURL(adapter)).href);
const channel = new WindowsAppChannel({ exclusiveFd3Startup: true, closeTimeoutMs: 5000 });
channel.on('error', () => { console.error('synthetic channel error'); process.exitCode = 72; });
const expected = Buffer.from(token);
await new Promise((resolve, reject) => {
  let bytes = Buffer.alloc(0);
  channel.on('data', function receive(part) {
    bytes = Buffer.concat([bytes, part]);
    if (bytes.length > expected.length) return reject(new Error('oversized challenge'));
    if (bytes.length === expected.length) {
      channel.off('data', receive);
      if (!bytes.equals(expected)) return reject(new Error('challenge mismatch'));
      resolve();
    }
  });
  channel.once('error', reject);
});
await new Promise((resolve, reject) => channel.write(Buffer.from('ack:' + token), e => e ? reject(e) : resolve()));
const child = spawn(process.execPath, ['-e', "process.stdout.write('ready\\n');process.stdin.resume();process.stdin.on('end',()=>process.exit(0));setTimeout(()=>process.exit(73),20000)"],
  { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
const exited = once(child, 'exit');
const [ready] = await once(child.stdout, 'data');
if (ready.toString() !== 'ready\n' || child.exitCode !== null) throw new Error('child readiness');
let stopped;
const closed = new Promise(resolve => { stopped = resolve; });
const managed = await startWithWindowsStop(win32.join(process.env.GENTLE_DOT_DATA_DIR, 'daemon.pid'), async () => ({
  closed,
  async close() {
    // Only the authenticated listener may initiate drain. Parent-side EOF is failure.
    const drained = await channel.close('drain');
    if (drained.mode !== 'drain' || drained.drained !== true || child.exitCode !== null) throw new Error('drain witness');
    console.log('DRAINED_CHILD_ALIVE');
    await new Promise(resolve => { const timer = setInterval(() => { if (existsSync(release)) { clearInterval(timer); resolve(); } }, 10); });
    if (child.exitCode !== null) throw new Error('child exited before release');
    child.stdin.end();
    const [code, signal] = await exited;
    if (code !== 0 || signal !== null) throw new Error('child did not exit normally');
    stopped();
  },
}));
console.log('STOP_READY');
await managed.closed;
clearTimeout(watchdog);
console.log('NORMAL_EXIT');
"#;
            let launch = LaunchSpec {
                program: env!("GENTLE_DOT_BUILD_NODE").into(),
                args: vec!["--input-type=module".into(), "-e".into(), script.into(),
                    adapter.to_str().unwrap().into(), release.to_str().unwrap().into(), token.clone()],
                envs: vec![("NODE_OPTIONS".into(), String::new())],
            };
            let (parent, endpoint) = crate::app_channel::windows::channel_pair().unwrap();
            let mut child = spawn(&launch, open_private_log(&root).unwrap(), &endpoint, &root).unwrap();
            drop(endpoint); // No parent-side client alias may invalidate the EOF witness.
            struct CloseChannel(crate::app_channel::ChannelStream);
            impl Drop for CloseChannel {
                fn drop(&mut self) { let _ = self.0.shutdown(); }
            }
            let channel_guard = CloseChannel(parent);
            let mut stream = channel_guard.0.try_clone().unwrap();
            let challenge = token.clone();
            let (tx, rx) = std::sync::mpsc::channel();
            let release_after_drain = release.clone();
            let reader = std::thread::spawn(move || {
                let result = (|| -> io::Result<()> {
                    stream.write_all(challenge.as_bytes())?;
                    let expected = format!("ack:{challenge}");
                    let mut reply = vec![0; expected.len()];
                    stream.read_exact(&mut reply)?;
                    if reply != expected.as_bytes() { return Err(io::Error::other("synthetic response mismatch")); }
                    let mut byte = [0];
                    if stream.read(&mut byte)? != 0 { return Err(io::Error::other("expected channel EOF")); }
                    // Release the live descendant only after daemon-side drain. The main
                    // thread stays in the production owned-stop path throughout.
                    std::fs::write(release_after_drain, b"release")?;
                    Ok(())
                })();
                let _ = tx.send(result);
            });
            let deadline = Instant::now() + Duration::from_secs(10);
            loop {
                let log = std::fs::read_to_string(&log_path).unwrap();
                if log.lines().any(|line| line == "STOP_READY") { break; }
                assert!(Instant::now() < deadline, "missing authenticated listener readiness: {log}");
                std::thread::sleep(Duration::from_millis(10));
            }
            // No EOF or release has been initiated by the parent. Both processes must
            // be live when the existing production method sends authenticated shutdown.
            assert!(child.status().unwrap().is_none());
            assert!(child.query().unwrap() >= 2);
            assert!(!release.exists());
            child.shutdown_owned(Duration::from_secs(10))
                .expect("authenticated owned shutdown before fd3 closure");
            assert!(!child.force_requested, "orderly shutdown must not enter the force path");
            child.shutdown_owned(Duration::ZERO).expect("checked orderly retry");
            rx.recv_timeout(Duration::from_secs(10)).expect("bounded fd3 exchange/drain").unwrap();
            reader.join().unwrap();
            assert!(child.status().unwrap().unwrap().success());
            assert_eq!(child.query().unwrap(), 0);
            assert!(std::fs::read_to_string(&log_path).unwrap().lines()
                .any(|line| line == "DRAINED_CHILD_ALIVE"));
            assert!(!root.join("daemon.pid").exists());
            channel_guard.0.shutdown().unwrap();
            assert!(std::fs::read_to_string(&log_path).unwrap().lines().any(|line| line == "NORMAL_EXIT"));
            // Retain this synthetic log/release directory; no recursive cleanup.
        }

        fn owned_fixture(script: &str) -> (WindowsChild, crate::app_channel::ChannelStream, PathBuf) {
            let mut nonce = [0u8; 16];
            getrandom::fill(&mut nonce).unwrap();
            let token: String = nonce.iter().map(|b| format!("{b:02x}")).collect();
            let root = std::env::temp_dir().join(format!("gentle-owned-stop-{token}"));
            ensure_record_directory(&root).unwrap();
            let launch = LaunchSpec {
                program: env!("GENTLE_DOT_BUILD_NODE").into(),
                args: vec!["-e".into(), script.into()],
                envs: vec![("NODE_OPTIONS".into(), String::new())],
            };
            let (parent, endpoint) = crate::app_channel::windows::channel_pair().unwrap();
            let child = spawn(&launch, open_private_log(&root).unwrap(), &endpoint, &root).unwrap();
            drop(endpoint);
            (child, parent, root)
        }

        fn force_group_with_unrelated_sentinel(root_exits: bool) {
            use std::os::windows::process::CommandExt;
            // Same executable, independently launched: never included in the owned Job.
            struct Sentinel(std::process::Child);
            impl Drop for Sentinel {
                fn drop(&mut self) { let _ = self.0.kill(); let _ = self.0.wait(); }
            }
            let mut sentinel = Sentinel(std::process::Command::new(env!("GENTLE_DOT_BUILD_NODE"))
                .args(["-e", "setTimeout(()=>{},30000)"])
                .env_remove("NODE_OPTIONS").creation_flags(CREATE_NO_WINDOW)
                .stdin(std::process::Stdio::null()).stdout(std::process::Stdio::null())
                .stderr(std::process::Stdio::null()).spawn().unwrap());
            let script = format!(r#"
const {{spawn}} = require('node:child_process');
// Outlive the Node root while still inheriting the retained outer owned Job.
const child = spawn(process.execPath, ['-e', "process.stdout.write('CHILD_READY\\n');setTimeout(()=>{{}},30000)"],
  {{stdio:['ignore','pipe','ignore'],windowsHide:true,detached:true}});
child.stdout.once('data', bytes => {{
  if (bytes.toString() !== 'CHILD_READY\n') process.exit(75);
  console.log('READY'); {}
}});
setTimeout(()=>process.exit(74),30000);
"#, if root_exits { "process.exit(0);" } else { "" });
            let (mut child, parent, root) = owned_fixture(&script);
            // Two Node starts on a cold CI runner can take more than 5 s; this only bounds the wait.
            let deadline = Instant::now() + Duration::from_secs(20);
            loop {
                let ready = std::fs::read_to_string(root.join("daemon.log")).unwrap().lines().any(|l| l == "READY");
                if ready && (!root_exits || child.status().unwrap().is_some()) { break; }
                assert!(Instant::now() < deadline, "synthetic root/descendant not ready");
                std::thread::sleep(Duration::from_millis(10));
            }
            assert!(child.query().unwrap() >= if root_exits { 1 } else { 2 });
            assert!(sentinel.0.try_wait().unwrap().is_none());
            let stopping = Instant::now();
            child.shutdown_owned(Duration::from_millis(50)).unwrap();
            assert!(stopping.elapsed() >= Duration::from_millis(50), "force must wait out grace");
            assert_eq!(child.status().unwrap().unwrap().code(), Some(if root_exits { 0 } else { 1 }));
            assert_eq!(child.query().unwrap(), 0);
            assert!(!root.join("daemon.pid").exists());
            assert!(child.stop.as_ref().is_none_or(|stop| stop.connect.is_none() && stop.write.is_none()));
            assert!(sentinel.0.try_wait().unwrap().is_none(), "same executable is not ownership");
            // A later parent-channel failure must not make retry require clean exit.
            child.shutdown_owned(Duration::ZERO).unwrap();
            parent.shutdown().unwrap();
        }

        #[test]
        fn owned_force_stops_root_and_descendants_not_same_executable() {
            force_group_with_unrelated_sentinel(false);
        }

        #[test]
        fn exited_root_still_requires_owned_descendant_completion() {
            force_group_with_unrelated_sentinel(true);
        }

        #[test]
        fn uncertain_status_keeps_an_established_launch_on_the_channel_open_stop() {
            let (mut child, parent, root) = owned_fixture("setTimeout(()=>{},30000)");
            assert!(child.established);
            // What the lifecycle does when an established launch's status query fails.
            child.retain_failure();
            assert!(child.launch_failed(), "uncertain status still refuses replacement and health");
            assert!(child.try_wait().is_err());
            assert!(child.shutdown_requires_channel(), "an established launch is not a failed startup");
            // No stop listener here: the authenticated attempt fails and the force path
            // waits out the caller's grace instead of the failed-startup zero grace.
            let stopping = Instant::now();
            child.shutdown_owned(Duration::from_millis(200)).unwrap();
            assert!(stopping.elapsed() >= Duration::from_millis(200), "established stop must honor its grace");
            assert!(child.force_requested);
            assert_eq!(child.query().unwrap(), 0);
            assert!(!root.join("daemon.pid").exists());
            parent.shutdown().unwrap();
        }

        #[test]
        fn owned_force_failures_retain_record_and_allow_checked_retry() {
            for faults in [
                Faults { terminate: true, ..Faults::default() },
                Faults { wait: true, ..Faults::default() },
                Faults { query: true, ..Faults::default() },
            ] {
                let (mut child, parent, root) = owned_fixture("setTimeout(()=>{},30000)");
                child.faults = faults;
                assert!(child.shutdown_owned(Duration::from_millis(50)).is_err());
                assert!(child.launch_failed());
                assert!(child.try_wait().is_err());
                assert!(root.join("daemon.pid").exists());
                child.faults = Faults::default();
                child.shutdown_owned(Duration::ZERO).unwrap();
                assert!(child.status().unwrap().is_some());
                assert_eq!(child.query().unwrap(), 0);
                assert!(!root.join("daemon.pid").exists());
                parent.shutdown().unwrap();
            }
        }

        #[test]
        fn multiple_cleanup_failures_retain_owner_until_checked_retry() {
            let (parent, child) = crate::app_channel::windows::channel_pair().unwrap();
            let log = File::open(std::env::current_exe().unwrap()).unwrap();
            let mut failure = spawn_with_faults(&spec(), log, &child, Faults {
                assignment: true, terminate: true, wait: true, query: true, ..Faults::default()
            }).unwrap_err();
            let detail = failure.cleanup.as_ref().unwrap().to_string();
            assert!(detail.contains("terminate") && detail.contains("wait") && detail.contains("job query"));
            let mut owner = failure.unfinished.take().unwrap();
            assert!(owner.launch_failed());
            // Never resumed: cleanup may close the channel first, its listener may not exist.
            assert!(!owner.shutdown_requires_channel());
            assert!(owner.try_wait().is_err());
            owner.faults = Faults::default();
            owner.shutdown_owned(Duration::ZERO).unwrap();
            assert_eq!(job_active(&owner.job).unwrap(), 0);
            assert!(owner.status().unwrap().is_some());
            parent.shutdown().unwrap();
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn fd3_layout_is_packed_and_native_width() {
        let handles = [0x11usize, 0x22, 0x33, 0x44];
        let bytes = fd3_bootstrap(handles).unwrap();
        assert_eq!(&bytes[..4], &4i32.to_ne_bytes());
        assert_eq!(&bytes[4..8], &[65, 1, 1, 9]);
        assert_eq!(bytes.len(), 8 + 4 * std::mem::size_of::<usize>());
        for (i, handle) in handles.iter().enumerate() {
            let start = 8 + i * std::mem::size_of::<usize>();
            assert_eq!(&bytes[start..start + std::mem::size_of::<usize>()], &handle.to_ne_bytes());
        }
    }

    #[test]
    fn generic_layout_copies_handles_at_unaligned_offset() {
        let handle = usize::MAX;
        let bytes = packed_bootstrap(&[9], &[handle]).unwrap();
        assert_eq!(&bytes[..4], &1i32.to_ne_bytes());
        assert_eq!(bytes[4], 9);
        assert_eq!(&bytes[5..], &handle.to_ne_bytes());
        assert_eq!(packed_bootstrap(&[], &[]).unwrap(), 0i32.to_ne_bytes());
    }

    #[test]
    fn invalid_counts_and_reserved_size_are_refused() {
        assert!(packed_bootstrap(&[1], &[]).is_err());
        let flags = vec![1; 65_536];
        let handles = vec![1; flags.len()];
        assert!(packed_bootstrap(&flags, &handles).is_err());
    }

    #[test]
    fn command_quotes_empty_spaces_quotes_and_trailing_slashes() {
        let wide = command_line("node.exe", &["".into(), "a b".into(), "a\"b".into(), "tail\\".into()]).unwrap();
        assert_eq!(wide.last(), Some(&0));
        let text = String::from_utf16(&wide[..wide.len() - 1]).unwrap();
        assert_eq!(text, "\"node.exe\" \"\" \"a b\" \"a\\\"b\" \"tail\\\\\"");
    }

    #[test]
    fn command_rejects_nul_and_excess_utf16_length() {
        assert!(command_line("node.exe", &["x\0y".into()]).is_err());
        assert!(command_line("node.exe", &["x".repeat(32_767)]).is_err());
    }
}