signal: the return trampoline was Linux-only, and a test that proves the rest

Went looking for why `X=$(echo hi)` hangs every shell. Did not find it. Found
two other things, and built the instrument that rules out the largest suspect.

**The signal return trampoline was ABI-blind.** deliver_signals() manufactures
a return address for the handler -- seven bytes on the user stack reading
`mov eax, 15 ; syscall`. Fifteen is *Linux's* rt_sigreturn, which is right for
anything musl-linked, and that is every port and every shell. For a first-party
binary it is native syscall 15, which is `open`. So a handler in any cmd/
program ran, returned into the trampoline, called open() with whatever the
handler had left in its registers, got -ENOENT, and carried on executing the
stack bytes after the trampoline.

    pid 14 sigtest: trap 14 err 4 rip 0x46ca7 addr 0xfffffffffffffffe
      rax=fffffffffffffffe ... rsp=46ca0
      ustack: 46e30 46ca0 50f0000000fb8 0 0 0

rip is rsp+7 -- one past a seven-byte trampoline -- and the third word of the
stack is the trampoline's own bytes. It emits the number for the process's ABI
now; syscall_map is the thing that says which numbering this process speaks.

**SIG_BLOCK, SIG_UNBLOCK and SIG_SETMASK were not defined anywhere.**
sys_sigprocmask branched on bare 0, 1 and 2 with the names in comments, so
anything outside the kernel had to spell the number and hope it had the right
one. Defined in posix.h, used in the kernel.

**cmd/sigtest** asserts the SIGCHLD/sigsuspend contract every shell is built
on, and it is written so a permissive stub cannot pass: a blocked SIGCHLD stays
pending, sigsuspend delivers an *already pending* signal without spinning, the
handler runs exactly once, the mask is restored, the child is still reapable,
and a signal arriving mid-wait also wakes it. Eight checks, all green. The
kernel's half of that contract is now proven rather than assumed, which is what
lets the remaining bug be pursued somewhere else.

Along with it, `rt_sigsuspend` in lib/usys.S -- the syscall existed and the
first-party library simply never exposed it.

On the hang itself: it is not job control, not SMP, not zsh (mksh does it too),
and not any value the kernel returns -- a full syscall trace is in
docs/history/kernel.md section 7, which also records what the contradiction
narrows to. That section had said "root cause not yet isolated" with three
suspects; all three are now eliminated, and the note says what to do next
instead of what to guess.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/plan/1.0.md

@@ -206,6 +206,24 @@ right then.
       in 18 after.** See [../architecture/kernel.md](../architecture/kernel.md),
       "Per-CPU state".
 
+- [ ] **`$(command substitution)` hangs every shell.** Not job control, not
+      SMP, not zsh — `mksh -c 'X=$(echo hi)'` hangs the same way, on one CPU,
+      with `set +m`. Pipelines, subshells, background jobs and foreground
+      externals all work; only `$( )` does not.
+
+      Narrowed a long way this session and still open. The kernel's half of
+      the SIGCHLD/sigsuspend contract is now *proven* rather than assumed —
+      `cmd/sigtest` asserts the whole pattern and passes — and a full syscall
+      trace of a hang shows every return value correct. The contradiction is
+      at one line of zsh's `waitforpid()`, which ends its loop on `ESRCH` from
+      `kill(pid, 0)`; the trace shows that `kill` returning ESRCH and the loop
+      being entered regardless. See
+      [../history/kernel.md](../history/kernel.md), section 7.
+
+      Two real bugs were found and fixed on the way: the signal-return
+      trampoline was hardcoded to Linux's `rt_sigreturn` number, so handlers
+      in first-party binaries called `open()` and then executed stack bytes;
+      and `SIG_BLOCK`/`SIG_UNBLOCK`/`SIG_SETMASK` were not defined anywhere.
 - [ ] **`getrusage` does not distinguish `RUSAGE_CHILDREN`** from `RUSAGE_SELF`.
 - [ ] **`/proc/<pid>/exe` is a regular file, not a symlink**, so `readlink()`
       fails and `ps -o comm` prints `[init]`. Symlinks themselves now work —