nx_guarded_run.nx
buildroot/runtime/nx_guarded_run.nx
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
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
structs
| none |
consts
| 23 | const NX_MAGIC_5000: i64 = 5000 |
| 24 | const NX_MAGIC_1500: i64 = 1500 |
| 26 | const NX_GR_TIMEOUT: i64 = 124 // GNU-timeout convention: child exceeded deadline (then SIGKILLed) |
| 27 | const NX_GR_SPAWN_FAIL: i64 = 125 // wait4 returned an error |
| 28 | const NX_GR_POLL_MS: i64 = 50 // wall-clock poll granularity |
| 29 | const NX_GR_SIGKILL: i64 = 9 // SIGTERM is NOT enough for these hangs (2026-06-10 lesson) |
functions
| 31 | func 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 } |
| 32 | func gr_putn(v: i64) -> i64 |
| 47 | func nx_guarded_run(path: *u8, argv: *i64, envp: *i64, deadline_ms: i64, called by 10: mainmainmaingb_rungatemainmain+4 calls 9: sys_forksys_dup3sys_execvesys_exitsys_mmapsys_now_ms+3 |
| 81 | func gr_argv2(a0: *u8, a1: *u8) -> *i64 |
| 87 | func main() -> i64 |