code wiki / (root) / nx_guarded_run.nx

nx_guarded_run.nx

buildroot/runtime/nx_guarded_run.nx

5786 B122 linesdepth 2pulls 2 transitivereach 15 importersview sourcekind tool
docsdependenciesstructsconstsfunctions

about

nx_guarded_run.nx -- the team's HANG-HANDLING capability (operator: "make sure the team is getting built to handle issues like this hang", 2026-06-10). module: nishi-core.exec.guarded_run capability: CORE_COMPUTE + GATE WHY: nx_sov_build_run's sbr_run forks + wait4(blocking) with NO deadline, so a child that hangs in a syscall (e.g. the validated-HTTPS read loop wedging on a host like en.wikipedia.org that never cleanly EOFs) wedges the runner -- and therefore the GATE -- forever. This session proved two things the hard way: (1) such hangs are REAL (example.com fetches 868B fine; wikipedia hangs 220s+); (2) plain `timeout` (SIGTERM) does NOT reap them -- only SIGKILL does. nx_guarded_run makes ANY run hang-proof: fork the child, poll wait4(WNOHANG) against a wall-clock DEADLINE, and on breach SIGKILL it and report a distinct TIMEOUT verdict the caller files as a defect instead of hanging. Sovereign: pure sys_fork/execve/wait4/nx_kill -- no GNU `timeout`, no shell. This is the substrate the Doctor/Engineer wrap around every crawl/fetch/build gate so a network or miscompile hang becomes a deterministic, filed TIMEOUT -- never a wedged session. Pairs with nx_progress_watchdog (in-process stall detection); this is the out-of-process KILL the watchdog lacks.

dependencies 1 imports · 10 importers

nx_syscalls.nx nx_guarded_run.nx nx_diora_live_reach_guarded.nx nx_diora_live_serp.nx nx_entity_discover.nx nx_gate_bite.nx nx_ignored_host_reach.nx nx_oeuvre_resolve.nx nx_pulse_worker.nx nx_swcompare_evidence.nx nx_wall_triage.nx nx_wd_core.nx

imports: nx_syscalls.nx

imported by: nx_diora_live_reach_guarded.nxnx_diora_live_serp.nxnx_entity_discover.nxnx_gate_bite.nxnx_ignored_host_reach.nxnx_oeuvre_resolve.nxnx_pulse_worker.nxnx_swcompare_evidence.nxnx_wall_triage.nxnx_wd_core.nx

call flow from main pre-order; caps 40 nodes / depth 6 declared; ↻ = already shown

main sys_mmap sys_openat_wr gr_puts sys_write gr_argv2 sys_mmap ↻ sys_now_ms sys_mmap ↻ sys_clock_gettime_mono nx_guarded_run sys_fork sys_dup3 sys_execve sys_exit sys_mmap ↻ sys_now_ms ↻ sys_wait4 nx_kill sys_sleep_ms sys_mmap ↻ sys_munmap gr_putn sys_write ↻ sys_mmap ↻

structs

none

consts

23const NX_MAGIC_5000: i64 = 5000
24const NX_MAGIC_1500: i64 = 1500
26const NX_GR_TIMEOUT: i64 = 124 // GNU-timeout convention: child exceeded deadline (then SIGKILLed)
27const NX_GR_SPAWN_FAIL: i64 = 125 // wait4 returned an error
28const NX_GR_POLL_MS: i64 = 50 // wall-clock poll granularity
29const NX_GR_SIGKILL: i64 = 9 // SIGTERM is NOT enough for these hangs (2026-06-10 lesson)

functions

31func gr_puts(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
called by 1: main calls 1: sys_write
32func gr_putn(v: i64) -> i64
called by 1: main calls 2: sys_writesys_mmap
47func nx_guarded_run(path: *u8, argv: *i64, envp: *i64, deadline_ms: i64,
81func gr_argv2(a0: *u8, a1: *u8) -> *i64
called by 1: main calls 1: sys_mmap
87func main() -> i64