nx_lockwatch.nx

nx_lockwatch.nx -- WHO HOLDS THIS PLANE'S LOCK, AND WHAT ARE THEY DOING? WHY THIS EXISTS. On 2026-08-06 a gate went RED with an UNCHANGED binary. The cause was not in the diff at all: one worker sat in kernel state D, wchan=wait_for_commit -- a filesystem journal commit -- HOLDING a plane lock, while its siblings sat in wchan=locks_lock_inode_wait. Establishing that took reading /proc/locks by hand, mapping an inode back to a lock file, then reading /proc/<pid>/wchan and /proc/<pid>/fd for every candidate. Three separate investigations that day ran the same manual procedure, and ss_plane_lock's own BUSY message now TELLS an operator to do it: "check /proc/<pid>/wchan: locks_lock_inode_wait = queued, wait_for_commit = wedged on disk" ★TELLING SOMEONE TO RUN A PROCEDURE IS NOT THE SAME AS SHIPPING IT. A diagnostic that only exists in a message is a diagnostic nobody runs at 3am. This is that procedure, as an organ. AND THE DISTINCTION IT DRAWS IS THE WHOLE POINT -- these look identical from outside and need OPPOSITE responses: QUEUED (wchan=locks_lock_inode_wait) -- healthy contention. Someone is working; wait. WEDGED (state D, wchan=wait_for_commit / io_schedule / similar) -- the holder is stuck in the kernel on I/O. Waiting will not help; the disk is the problem, and every writer behind it is now blocked for as long as that lasts. STALE -- a lock file whose recorded holder is GONE. flock releases on process death, so this should be impossible; if it ever prints, the assumption is wrong and that matters more than anything else on the report. READ-ONLY. Opens nothing but /proc and the lock files' metadata; writes nothing, locks nothing -- deliberately, because an instrument that took the lock it is diagnosing would be the defect. usage: nx_lockwatch [store-dir] default knowledge/store exit: 0 = no held plane locks, 1 = at least one held, 2 = usage/unreadable license_tier: ORIGINAL No hw writes (Rule 26).