@vibesdotdev/host-bun 0.0.0-stage → 1.0.0-rc.3

package/native/held-launch/src/lib.rs

@@ -0,0 +1,528 @@
+//! Execution owner's native ABI. One opaque handle retains one actual Child.
+//! Calls on a handle must be serialized; a pointer is valid until dispose=1.
+//! No runtime, process registry, identity resolver, timer, or secret lookup.
+#![cfg(any(target_os = "macos", target_os = "linux"))]
+
+mod events;
+
+use std::ffi::{CStr, c_char, c_int, c_ulong};
+use std::fs::File;
+use std::io::{self, Write};
+use std::os::fd::{AsRawFd, FromRawFd, IntoRawFd};
+use std::os::unix::net::UnixStream;
+use std::os::unix::process::ExitStatusExt;
+use std::os::unix::process::CommandExt;
+use std::path::Path;
+use std::process::{Command, Stdio};
+use vibes_native_core::held_launch::{ControlInterest, ExecStatus, HeldChild, LaunchError, NativeIdentity,
+    exec_after_release_with_stdio, read_declared_launch_payload, report_exec_failure};
+use vibes_native_core::process_identity::read_process_identity;
+
+vibes_native_core::last_error_plane!(vhl);
+
+#[cfg(target_os = "macos")]
+const OPEN_PTY_FLAGS: c_int = 2 | 0x0002_0000 | 0x0100_0000;
+#[cfg(target_os = "linux")]
+const OPEN_PTY_FLAGS: c_int = 2 | 0x100 | 0x80000;
+#[cfg(target_os = "macos")]
+const TIOCSCTTY: c_ulong = 0x2000_7461;
+#[cfg(target_os = "linux")]
+const TIOCSCTTY: c_ulong = 0x540e;
+#[cfg(target_os = "macos")]
+const TIOCSWINSZ: c_ulong = 0x8008_7467;
+#[cfg(target_os = "linux")]
+const TIOCSWINSZ: c_ulong = 0x5414;
+#[cfg(target_os = "macos")]
+const O_NONBLOCK: c_int = 0x4;
+#[cfg(target_os = "linux")]
+const O_NONBLOCK: c_int = 0x800;
+
+unsafe extern "C" {
+    fn posix_openpt(flags: c_int) -> c_int;
+    fn grantpt(fd: c_int) -> c_int;
+    fn unlockpt(fd: c_int) -> c_int;
+    fn ptsname_r(fd: c_int, buffer: *mut c_char, len: usize) -> c_int;
+    fn open(path: *const c_char, flags: c_int, ...) -> c_int;
+    fn ioctl(fd: c_int, request: c_ulong, ...) -> c_int;
+    fn dup2(old: c_int, new: c_int) -> c_int;
+    fn fcntl(fd: c_int, command: c_int, ...) -> c_int;
+    fn getrlimit(resource: c_int, limit: *mut ResourceLimit) -> c_int;
+    fn setrlimit(resource: c_int, limit: *const ResourceLimit) -> c_int;
+    fn fork() -> c_int;
+    fn setsid() -> c_int;
+}
+
+#[repr(C)]
+struct ResourceLimit { soft: u64, hard: u64 }
+#[cfg(target_os = "macos")]
+const NOFILE: c_int = 8;
+#[cfg(target_os = "linux")]
+const NOFILE: c_int = 7;
+
+/// The helper is already exec'd: no allocation or host policy runs between fork and exec.
+fn require_fd_floor(floor: u64) -> io::Result<()> {
+    if floor == 0 { return Ok(()); }
+    let mut limit = ResourceLimit { soft: 0, hard: 0 };
+    if unsafe { getrlimit(NOFILE, &mut limit) } < 0 { return Err(io::Error::last_os_error()); }
+    if limit.soft >= floor { return Ok(()); }
+    if limit.hard < floor { return Err(io::Error::from(io::ErrorKind::PermissionDenied)); }
+    let requested = ResourceLimit { soft: floor, hard: limit.hard };
+    if unsafe { setrlimit(NOFILE, &requested) } < 0 { return Err(io::Error::last_os_error()); }
+    if unsafe { getrlimit(NOFILE, &mut limit) } < 0 { return Err(io::Error::last_os_error()); }
+    if limit.soft < floor || limit.hard != requested.hard { return Err(io::Error::from(io::ErrorKind::PermissionDenied)); }
+    Ok(())
+}
+
+/// Preserve existing flags; failure leaves the descriptor with its native owner.
+fn prepare_transferred_fd(fd: c_int) -> io::Result<()> {
+    unsafe {
+        let descriptor_flags = fcntl(fd, 1); // F_GETFD
+        if descriptor_flags < 0 { return Err(io::Error::last_os_error()); }
+        if fcntl(fd, 2, descriptor_flags | 1) < 0 { return Err(io::Error::last_os_error()); } // F_SETFD, FD_CLOEXEC
+        let status_flags = fcntl(fd, 3); // F_GETFL
+        if status_flags < 0 { return Err(io::Error::last_os_error()); }
+        if fcntl(fd, 4, status_flags | O_NONBLOCK) < 0 { return Err(io::Error::last_os_error()); } // F_SETFL
+    }
+    Ok(())
+}
+
+#[repr(C)]
+struct WindowSize { rows: u16, cols: u16, xpixel: u16, ypixel: u16 }
+
+/// ABI error text contains only stable phases and numeric errno.
+fn record(phase: &str, errno: Option<i32>) -> i32 {
+    set_last_error(format!("{phase}:errno={}", errno.unwrap_or(0)));
+    -1
+}
+fn launch_error(error: LaunchError) -> i32 { record(error.phase, error.errno) }
+fn invalid() -> io::Error { io::Error::from(io::ErrorKind::InvalidInput) }
+
+struct Cursor<'a> { bytes: &'a [u8], offset: usize }
+impl<'a> Cursor<'a> {
+    fn take(&mut self, len: usize) -> io::Result<&'a [u8]> {
+        let end = self.offset.checked_add(len).ok_or_else(invalid)?;
+        let value = self.bytes.get(self.offset..end).ok_or_else(invalid)?;
+        self.offset = end;
+        Ok(value)
+    }
+    fn count(&mut self) -> io::Result<usize> {
+        let bytes: [u8; 4] = self.take(4)?.try_into().map_err(|_| invalid())?;
+        Ok(u32::from_be_bytes(bytes) as usize)
+    }
+    fn string(&mut self) -> io::Result<&'a str> {
+        let len = self.count()?;
+        let value = std::str::from_utf8(self.take(len)?).map_err(|_| invalid())?;
+        if value.as_bytes().contains(&0) { return Err(invalid()); }
+        Ok(value)
+    }
+}
+
+/// VHLW2\0, u64 minimum NOFILE (zero absent), command/cwd, argc, envc.
+/// Counts/string lengths are u32 big-endian. No trailing bytes, NULs or implicit env.
+fn workload(bytes: &[u8]) -> io::Result<(Command, u64)> {
+    let mut cursor = Cursor { bytes, offset: 0 };
+    if cursor.take(6)? != b"VHLW2\0" { return Err(invalid()); }
+    let floor = u64::from_be_bytes(cursor.take(8)?.try_into().map_err(|_| invalid())?);
+    if floor > 9_007_199_254_740_991 { return Err(invalid()); }
+    let executable = cursor.string()?;
+    let cwd = cursor.string()?;
+    if !Path::new(executable).is_absolute() || !Path::new(cwd).is_absolute() { return Err(invalid()); }
+    let mut command = Command::new(executable);
+    command.current_dir(cwd).env_clear();
+    for _ in 0..cursor.count()? { command.arg(cursor.string()?); }
+    for _ in 0..cursor.count()? {
+        let name = cursor.string()?;
+        if name.is_empty() || name.contains('=') { return Err(invalid()); }
+        command.env(name, cursor.string()?);
+    }
+    if cursor.offset != bytes.len() { return Err(invalid()); }
+    Ok((command, floor))
+}
+
+fn stdio(mode: u8) -> io::Result<Stdio> {
+    match mode { 0 => Ok(Stdio::piped()), 1 => Ok(Stdio::inherit()), 2 => Ok(Stdio::null()), _ => Err(invalid()) }
+}
+
+fn resize(fd: c_int, cols: u16, rows: u16) -> io::Result<()> {
+    if cols == 0 || rows == 0 { return Err(invalid()); }
+    let size = WindowSize { rows, cols, xpixel: 0, ypixel: 0 };
+    if unsafe { ioctl(fd, TIOCSWINSZ, &size) } < 0 { return Err(io::Error::last_os_error()); }
+    Ok(())
+}
+
+fn pty(cols: u16, rows: u16) -> io::Result<(File, File)> {
+    // Atomic CLOEXEC at creation; never use openpty followed by a racy fcntl.
+    let master_fd = unsafe { posix_openpt(OPEN_PTY_FLAGS) };
+    if master_fd < 0 { return Err(io::Error::last_os_error()); }
+    let master = unsafe { File::from_raw_fd(master_fd) };
+    if unsafe { grantpt(master_fd) } < 0 || unsafe { unlockpt(master_fd) } < 0 {
+        return Err(io::Error::last_os_error());
+    }
+    // This is a native device-name buffer, not a workload/resource budget.
+    let mut path = [0 as c_char; 4096];
+    let result = unsafe { ptsname_r(master_fd, path.as_mut_ptr(), path.len()) };
+    if result != 0 { return Err(if result > 0 { io::Error::from_raw_os_error(result) } else { io::Error::last_os_error() }); }
+    let slave_fd = unsafe { open(path.as_ptr(), OPEN_PTY_FLAGS) };
+    if slave_fd < 0 { return Err(io::Error::last_os_error()); }
+    let slave = unsafe { File::from_raw_fd(slave_fd) };
+    resize(master_fd, cols, rows)?;
+    Ok((master, slave))
+}
+
+pub struct Launch {
+    child: Option<HeldChild>,
+    master: Option<File>,
+    master_transferred: bool,
+}
+
+/// All pointer/length pairs are caller-owned valid memory for the call. Handles
+/// cannot be forged, aliased concurrently, or used after successful dispose.
+unsafe fn launch<'a>(pointer: *mut Launch) -> Result<&'a mut Launch, i32> {
+    unsafe { pointer.as_mut() }.ok_or_else(|| record("handle-invalid", None))
+}
+unsafe fn bytes<'a>(pointer: *const u8, len: usize) -> io::Result<&'a [u8]> {
+    if len == 0 { return Ok(&[]); }
+    if pointer.is_null() || len > isize::MAX as usize { return Err(invalid()); }
+    Ok(unsafe { vibes_native_core::byte_slice(pointer, len) })
+}
+unsafe fn path<'a>(pointer: *const c_char) -> io::Result<&'a str> {
+    if pointer.is_null() { return Err(invalid()); }
+    let value = unsafe { CStr::from_ptr(pointer) }.to_str().map_err(|_| invalid())?;
+    if !Path::new(value).is_absolute() { return Err(invalid()); }
+    Ok(value)
+}
+
+/// stdin/out/err: 0 pipe, 1 inherit, 2 ignore. cols=rows=0 selects pipes;
+/// nonzero cols AND rows select PTY. helper cwd is an explicit host declaration.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_spawn(helper: *const c_char, helper_cwd: *const c_char,
+    payload: *const u8, len: usize, max_payload_bytes: usize, stdin: u8, stdout: u8, stderr: u8,
+    cols: u16, rows: u16) -> *mut Launch
+{
+    let prepared = (|| -> io::Result<(Command, Vec<u8>, Option<File>)> {
+        if max_payload_bytes == 0 || max_payload_bytes >= isize::MAX as usize || len > max_payload_bytes {
+            return Err(invalid());
+        }
+        let bytes = unsafe { bytes(payload, len)? };
+        let _validated = workload(bytes)?;
+        let mut helper = Command::new(unsafe { path(helper)? });
+        helper.current_dir(unsafe { path(helper_cwd)? }).env_clear();
+        let terminal = cols != 0 || rows != 0;
+        let master = if terminal {
+            if cols == 0 || rows == 0 { return Err(invalid()); }
+            let (master, slave) = pty(cols, rows)?;
+            helper.stdin(Stdio::from(slave.try_clone()?))
+                .stdout(Stdio::from(slave.try_clone()?)).stderr(Stdio::from(slave));
+            Some(master)
+        } else {
+            helper.stdin(stdio(stdin)?).stdout(stdio(stdout)?).stderr(stdio(stderr)?);
+            None
+        };
+        let mut framed = Vec::new();
+        framed.try_reserve_exact(bytes.len().checked_add(1).ok_or_else(invalid)?)
+            .map_err(|_| io::Error::from(io::ErrorKind::OutOfMemory))?;
+        framed.push(u8::from(terminal));
+        framed.extend_from_slice(bytes);
+        Ok((helper, framed, master))
+    })();
+    let (helper, payload, master) = match prepared {
+        Ok(prepared) => prepared,
+        Err(error) => { record("launch-prepare", error.raw_os_error()); return std::ptr::null_mut(); }
+    };
+    // The protocol's terminal tag is fixed overhead, outside the workload budget.
+    match HeldChild::spawn_with_payload(helper, |fd| fd.to_string(), payload, max_payload_bytes + 1) {
+        Ok(child) => Box::into_raw(Box::new(Launch { child: Some(child), master, master_transferred: false })),
+        Err(error) => { launch_error(error); std::ptr::null_mut() }
+    }
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_pid(pointer: *mut Launch) -> i64 {
+    match unsafe { launch(pointer) } { Ok(handle) => handle.child.as_ref().map_or(-1, |child| i64::from(child.pid())), Err(_) => -1 }
+}
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_control_fd(pointer: *mut Launch) -> i32 {
+    match unsafe { launch(pointer) } { Ok(handle) => handle.child.as_ref().map_or(-1, |child| child.control_event().0.as_raw_fd()), Err(error) => error }
+}
+/// 1 readable, 2 writable; borrowed descriptor, level-triggered registration.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_control_interest(pointer: *mut Launch) -> i32 {
+    match unsafe { launch(pointer) } {
+        Ok(handle) => match handle.child.as_ref().map(|child| child.control_event().1) {
+            Some(ControlInterest::Readable) => 1, Some(ControlInterest::Writable) => 2, None => -1
+        }, Err(error) => error
+    }
+}
+
+unsafe fn identity(pid: u32, sid: u32, token: *const u8, len: usize) -> io::Result<NativeIdentity> {
+    let token = std::str::from_utf8(unsafe { bytes(token, len)? }).map_err(|_| invalid())?;
+    if token.is_empty() || token.as_bytes().contains(&0) { return Err(invalid()); }
+    Ok(NativeIdentity { pid, session_id: sid, start_token: token.to_owned() })
+}
+
+/// Read identity for this retained child, never an arbitrary caller-supplied pid.
+/// Success returns the UTF-8 token length (not NUL terminated) and writes pid/sid
+/// to out[0]/out[1]. Failure=-1; no output is written on insufficient capacity.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_identity(pointer: *mut Launch, out: *mut u32,
+    token: *mut u8, capacity: usize) -> isize
+{
+    if out.is_null() || token.is_null() || capacity > isize::MAX as usize {
+        return record("identity-output-invalid", None) as isize;
+    }
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error as isize };
+    let Some(child) = handle.child.as_mut() else { return record("handle-disposed", None) as isize; };
+    match child.try_reap() {
+        Ok(None) => {},
+        Ok(Some(_)) => return record("identity-child-exited", None) as isize,
+        Err(error) => return launch_error(error) as isize,
+    }
+    let observed = match read_process_identity(child.pid()) {
+        Ok(Some(identity)) => identity,
+        Ok(None) => return record("identity-child-absent", None) as isize,
+        Err(error) => return record("identity-read", error.raw_os_error()) as isize,
+    };
+    match child.try_reap() {
+        Ok(None) => {},
+        Ok(Some(_)) => return record("identity-child-exited", None) as isize,
+        Err(error) => return launch_error(error) as isize,
+    }
+    let bytes = observed.start_token.as_bytes();
+    if capacity < bytes.len() { return record("identity-output-capacity", None) as isize; }
+    unsafe {
+        out.write(observed.pid);
+        out.add(1).write(observed.session_id);
+        std::ptr::copy_nonoverlapping(bytes.as_ptr(), token, bytes.len());
+    }
+    bytes.len() as isize
+}
+
+/// 0 pending, 1 complete READY frame, -1 failure. Only after 1 should the
+/// adapter obtain its canonical identity snapshot and call vhl_ready.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_advance_ready(pointer: *mut Launch) -> i32 {
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error };
+    let Some(child) = handle.child.as_mut() else { return record("handle-disposed", None); };
+    match child.try_ready_message() { Ok(true) => 1, Ok(false) => 0, Err(error) => launch_error(error) }
+}
+
+/// 0 pending, 1 READY admitted, -1 fixed error. Identity comes from the canonical
+/// process owner, never from this library. The actual retained Child is checked.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_ready(pointer: *mut Launch, pid: u32, sid: u32, token: *const u8, len: usize) -> i32 {
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error };
+    let identity = match unsafe { identity(pid, sid, token, len) } { Ok(identity) => identity, Err(_) => return record("identity-invalid", None) };
+    let Some(child) = handle.child.as_mut() else { return record("handle-disposed", None); };
+    match child.try_ready(|_| Ok(identity)) { Ok(Some(_)) => 1, Ok(None) => 0, Err(error) => launch_error(error) }
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_release(pointer: *mut Launch, pid: u32, sid: u32, token: *const u8, len: usize) -> i32 {
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error };
+    let identity = match unsafe { identity(pid, sid, token, len) } { Ok(identity) => identity, Err(_) => return record("identity-invalid", None) };
+    let Some(child) = handle.child.as_mut() else { return record("handle-disposed", None); };
+    match child.release(|_| Ok(identity)) { Ok(()) => 1, Err(error) => launch_error(error) }
+}
+
+/// Transfer one FD exactly once: 0 stdin, 1 stdout, 2 stderr, 3 PTY master.
+/// Admission sets O_NONBLOCK and FD_CLOEXEC before transfer, retaining custody
+/// on failure. Child-side pipe ends and the PTY slave remain blocking.
+/// -2 is an undeclared/already-transferred stream; -1 is an actual failure.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_take_fd(pointer: *mut Launch, stream: u8) -> i32 {
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error };
+    let Some(child) = handle.child.as_mut() else { return record("handle-disposed", None); };
+    let pipe = match stream { 0 => child.stdin_fd(), 1 => child.stdout_fd(), 2 => child.stderr_fd(), _ => None };
+    if let Some(fd) = pipe {
+        if let Err(error) = prepare_transferred_fd(fd) { return record("stream-transfer-flags", error.raw_os_error()); }
+    }
+    match stream {
+        0 => child.take_stdin().map_or(-2, IntoRawFd::into_raw_fd),
+        1 => child.take_stdout().map_or(-2, IntoRawFd::into_raw_fd),
+        2 => child.take_stderr().map_or(-2, IntoRawFd::into_raw_fd),
+        3 => {
+            if handle.master_transferred { return -2; }
+            let Some(master) = &handle.master else { return -2; };
+            match master.try_clone() {
+                Ok(fd) => {
+                    if let Err(error) = prepare_transferred_fd(fd.as_raw_fd()) { return record("pty-transfer-flags", error.raw_os_error()); }
+                    handle.master_transferred = true;
+                    fd.into_raw_fd()
+                },
+                Err(error) => record("pty-transfer", error.raw_os_error())
+            }
+        },
+        _ => record("stream-invalid", None)
+    }
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_resize(pointer: *mut Launch, cols: u16, rows: u16) -> i32 {
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error };
+    let Some(master) = &handle.master else { return record("pty-unavailable", None); };
+    match resize(master.as_raw_fd(), cols, rows) { Ok(()) => 1, Err(error) => record("pty-resize", error.raw_os_error()) }
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_terminate(pointer: *mut Launch) -> i32 {
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error };
+    let Some(child) = handle.child.as_mut() else { return record("handle-disposed", None); };
+    match child.terminate_child() { Ok(()) => 1, Err(error) => launch_error(error) }
+}
+
+/// 0 pending, 1 reaped, -1 error. out[0]=exit code (-1 absent), out[1]=signal
+/// number (0 absent). Only actual parent wait evidence populates these values.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_reap(pointer: *mut Launch, out: *mut i32) -> i32 {
+    if out.is_null() { return record("reap-output-invalid", None); }
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error };
+    let Some(child) = handle.child.as_mut() else { return record("handle-disposed", None); };
+    match child.try_reap() {
+        Ok(None) => 0,
+        Ok(Some(status)) => { unsafe { out.write(status.code().unwrap_or(-1)); out.add(1).write(status.signal().unwrap_or(0)); } 1 },
+        Err(error) => launch_error(error)
+    }
+}
+
+/// 0 pending, 1 control closed (NOT exit), 2 exec failure with out[0]=errno.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_exec_status(pointer: *mut Launch, out: *mut i32) -> i32 {
+    if out.is_null() { return record("exec-status-output-invalid", None); }
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error };
+    let Some(child) = handle.child.as_mut() else { return record("handle-disposed", None); };
+    match child.try_exec_status() {
+        Ok(None) => 0,
+        Ok(Some(ExecStatus::ControlClosed)) => 1,
+        Ok(Some(ExecStatus::Failed(errno))) => { unsafe { out.write(errno); } 2 },
+        Err(error) => launch_error(error)
+    }
+}
+
+/// Success=1 invalidates the pointer. Failure=-1 RETAINS it and its child.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn vhl_dispose(pointer: *mut Launch) -> i32 {
+    let handle = match unsafe { launch(pointer) } { Ok(handle) => handle, Err(error) => return error };
+    let Some(child) = handle.child.take() else { return record("handle-disposed", None); };
+    match child.try_dispose() {
+        Ok(()) => { drop(unsafe { Box::from_raw(pointer) }); 1 },
+        Err((child, error)) => { handle.child = Some(child); launch_error(error) }
+    }
+}
+
+/// Called only by this cohort's trusted helper executable. The received bytes
+/// have no authority to choose another resolver or supervisor.
+pub fn run_helper(mut control: UnixStream) -> (&'static str, Option<i32>) {
+    let payload = match read_declared_launch_payload(&mut control) {
+        Ok(payload) => payload,
+        Err(error) => return ("payload-read", error.raw_os_error())
+    };
+    let Some((&terminal, bytes)) = payload.split_first() else { return ("payload-invalid", None); };
+    if terminal > 1 { return ("payload-invalid", None); }
+    let (mut command, floor) = match workload(bytes) {
+        Ok(command) => command,
+        Err(error) => return ("payload-invalid", error.raw_os_error())
+    };
+    let mut status = match control.try_clone() {
+        Ok(status) => status,
+        Err(error) => return ("status-duplicate", error.raw_os_error())
+    };
+    let error = exec_after_release_with_stdio(control, &mut command, || {
+        require_fd_floor(floor)?;
+        if terminal == 1 {
+            if unsafe { ioctl(0, TIOCSCTTY, 0) } < 0 { return Err(io::Error::last_os_error()); }
+            if unsafe { dup2(0, 1) } < 0 || unsafe { dup2(0, 2) } < 0 { return Err(io::Error::last_os_error()); }
+        }
+        Ok(())
+    });
+    if let Err(report) = report_exec_failure(&mut status, error.raw_os_error()) {
+        return ("exec-status-write", report.raw_os_error());
+    }
+    ("helper-exec", error.raw_os_error())
+}
+
+/// Ordinary caller-owned ChildProcess handoff: no setsid, identity or membership owner.
+/// The parent's native spawn has already chosen detached/stdio dispositions.
+pub fn run_direct_helper(mut control: UnixStream) -> (&'static str, Option<i32>) {
+    let prepared = (|| -> io::Result<(Command, u64)> {
+        let payload = read_declared_launch_payload(&mut control)?;
+        workload(&payload)
+    })();
+    let (mut command, floor) = match prepared {
+        Ok(value) => value,
+        Err(error) => {
+            if let Err(report) = direct_failure(&mut control, b"FAIL", error.raw_os_error()) {
+                return ("exec-status-write", report.raw_os_error());
+            }
+            return ("payload-invalid", error.raw_os_error());
+        }
+    };
+    let fd = control.as_raw_fd();
+    let setup = (|| -> io::Result<()> {
+        let flags = unsafe { fcntl(fd, 1) };
+        if flags < 0 || unsafe { fcntl(fd, 2, flags | 1) } < 0 { return Err(io::Error::last_os_error()); }
+        require_fd_floor(floor)
+    })();
+    if let Err(error) = setup {
+        if let Err(report) = direct_failure(&mut control, b"FDNO", error.raw_os_error()) {
+            return ("exec-status-write", report.raw_os_error());
+        }
+        return ("fd-floor", error.raw_os_error());
+    }
+    if let Err(error) = control.write_all(b"VFD2RDY\n") { return ("ready-write", error.raw_os_error()); }
+    let error = command.exec();
+    if let Err(report) = direct_failure(&mut control, b"EXEC", error.raw_os_error()) { return ("exec-status-write", report.raw_os_error()); }
+    ("helper-exec", error.raw_os_error())
+}
+
+/// Daemon handoff: this helper is the launcher's child and exits as soon as it has forked the
+/// workload, so the system reparents the workload and it is never a descendant of the launcher.
+/// The workload starts its own session (pid = pgid = sid), applies the floor, reports its pid in
+/// the fixed `VFD2DMN\n` + u32 big-endian frame and execs. The helper's exit and the workload's
+/// CLOEXEC exec together end the stream: EOF after the pid frame with no failure frame is the exec
+/// receipt. `None` is the helper's own success (exit 0); `Some` is a fixed phase/errno (exit 126).
+pub fn run_daemon_helper(mut control: UnixStream) -> Option<(&'static str, Option<i32>)> {
+    let prepared = (|| -> io::Result<(Command, u64)> {
+        let payload = read_declared_launch_payload(&mut control)?;
+        workload(&payload)
+    })();
+    let (mut command, floor) = match prepared {
+        Ok(value) => value,
+        Err(error) => return Some(daemon_failure(&mut control, b"FAIL", "payload-invalid", error))
+    };
+    let fd = control.as_raw_fd();
+    let flags = unsafe { fcntl(fd, 1) };
+    if flags < 0 || unsafe { fcntl(fd, 2, flags | 1) } < 0 {
+        return Some(daemon_failure(&mut control, b"FAIL", "control-cloexec", io::Error::last_os_error()));
+    }
+    // The helper is single-threaded (already exec'd), so the forked workload may run ordinary code before its exec.
+    match unsafe { fork() } {
+        pid if pid < 0 => Some(daemon_failure(&mut control, b"FORK", "fork", io::Error::last_os_error())),
+        0 => {
+            if unsafe { setsid() } < 0 {
+                return Some(daemon_failure(&mut control, b"SSID", "setsid", io::Error::last_os_error()));
+            }
+            if let Err(error) = require_fd_floor(floor) {
+                return Some(daemon_failure(&mut control, b"FDNO", "fd-floor", error));
+            }
+            let mut ready = *b"VFD2DMN\n\0\0\0\0";
+            ready[8..].copy_from_slice(&std::process::id().to_be_bytes());
+            if let Err(error) = control.write_all(&ready) { return Some(("ready-write", error.raw_os_error())); }
+            let error = command.exec();
+            Some(daemon_failure(&mut control, b"EXEC", "helper-exec", error))
+        }
+        _ => None
+    }
+}
+
+/// Report one fixed failure frame; a frame that cannot be written is reported as the write failure.
+fn daemon_failure(control: &mut UnixStream, phase: &[u8; 4], name: &'static str, error: io::Error) -> (&'static str, Option<i32>) {
+    match direct_failure(control, phase, error.raw_os_error()) {
+        Ok(()) => (name, error.raw_os_error()),
+        Err(report) => ("exec-status-write", report.raw_os_error())
+    }
+}
+
+fn direct_failure(control: &mut UnixStream, phase: &[u8; 4], errno: Option<i32>) -> io::Result<()> {
+    control.write_all(phase)?;
+    control.write_all(&errno.unwrap_or(0).to_be_bytes())
+}

package/native/held-launch/symbols.golden

@@ -0,0 +1,21 @@
+_vhl_advance_ready
+_vhl_control_fd
+_vhl_control_interest
+_vhl_dispose
+_vhl_events_cancel
+_vhl_events_create
+_vhl_events_dispose
+_vhl_events_finish
+_vhl_events_watch_child
+_vhl_events_watch_fd
+_vhl_exec_status
+_vhl_identity
+_vhl_last_error
+_vhl_pid
+_vhl_ready
+_vhl_reap
+_vhl_release
+_vhl_resize
+_vhl_spawn
+_vhl_take_fd
+_vhl_terminate