Take up the unit as a handle, and record the SIGPIPE this cannot yet quiet

`kal_spawn.job' and `kal_process_job_enter' are both `setpgid' here: the unit's
identity is the first member's, reported back to the caller. `job_terminate' uses
the signal that cannot be declined --- a unit contains programs the caller never
held a handle to, so a request any member may ignore does not terminate it.

⚠️⚠️ AND A DEFECT IS RECORDED RATHER THAN GUESSED AT. openkal defines no signals,
and `kal_stream_write' is required to REPORT that a stream's far end is gone ---
while this kernel delivers SIGPIPE, whose default action ends the program. A C
library above answers `signal(SIGPIPE, SIG_IGN)' truthfully, having nothing to
set, and the program is killed anyway by a mechanism no layer between can name.

openkal-linux now ignores it in one call at startup. This kernel's `sigaction'
takes a structure carrying a trampoline its C library supplies, and a disposition
installed with the wrong shape shows up as a program dying in a way nobody can
trace --- which is the defect this note is about, arrived at from the other side.
So it waits until it can be MEASURED here, and the consequence is stated in the
file rather than discovered by whoever meets it.

Author: Sunrisepeak

src/env.cpp

@@ -18,6 +18,35 @@ void record(int argc, char** argv, char** envp) {
 }  // namespace okm
 
 namespace {
+
+// ⚠️⚠️ A PROGRAM ABOVE openkal SHALL NOT BE ENDED BY SOMETHING openkal NEVER TOLD
+// IT ABOUT. openkal defines no signals, and `kal_stream_write' is required to
+// REPORT that the far end of a stream is gone --- while this kernel delivers
+// SIGPIPE, whose default action ends the program instead.
+//
+// ⭐ A C library above answers `signal(SIGPIPE, SIG_IGN)' truthfully, because
+// openkal has no signals and there is nothing for it to set; the program is then
+// killed anyway, by a mechanism no layer between it and here can name. Ignored
+// at this level because this is the only level that can. Found on the other
+// implementation, fixed on both --- a divergence here would be the same defect
+// with a different exit status.
+//
+// ⚠️ Not a policy about signals in general: this is the one an ordinary openkal
+// operation provokes.
+//
+// ⚠️⚠️ AND IT IS NOT FIXED HERE YET, WHICH IS RECORDED RATHER THAN LEFT TO BE
+// DISCOVERED. openkal-linux ignores it in one call. This kernel's `sigaction'
+// takes a `struct __sigaction' carrying a TRAMPOLINE that its C library
+// supplies, and a disposition installed with the wrong shape is the kind of
+// mistake that shows up as a program dying in a way nobody can trace --- which is
+// the defect this note is about, arrived at from the other side.
+//
+// ⇒ It is left until it can be MEASURED on this system. This repository already
+// refuses to claim a facility it has not exercised, and a signal disposition
+// installed by guesswork is exactly that. The consequence meanwhile is stated:
+// a program above this implementation that writes to a stream whose far end has
+// gone is ended by SIGPIPE rather than told, and no layer between it and here
+// can name what happened.
 [[gnu::constructor(101)]] void capture(int argc, char** argv, char** envp) {
     if (okm::g_argv == nullptr) okm::record(argc, argv, envp);
 }

src/process.cpp

@@ -236,6 +236,18 @@ int kal_process_terminate(kal_process h) {
     return okm::failed(r) ? okm::translate(r) : kal_ok;
 }
 
+// This program itself joins or forms a unit --- what `kal_spawn.job' cannot say,
+// because that places a program the caller STARTS and a copy wishing to lead a
+// unit must say so about ITSELF before it replaces itself.
+int kal_process_job_enter(kal_job* j) {
+    if (j == nullptr) return kal_err_invalid;
+    const okm_long join = static_cast<okm_long>(j->h);
+    const okm_long r = okm::sys(nr_setpgid, 0, join);
+    if (okm::failed(r)) return okm::translate(r);
+    if (join == 0) j->h = static_cast<kal_uintptr>(okm::sys(okm::nr_getpid));
+    return kal_ok;
+}
+
 // Every program in the unit, including ones never held as a handle.
 //
 // ⚠️ A group is named by a process identifier, and those are reused: once the
@@ -244,7 +256,10 @@ int kal_process_terminate(kal_process h) {
 // than hidden.
 int kal_process_job_terminate(kal_job j) {
     if (j.h == 0) return kal_err_invalid;
-    const okm_long r = okm::sys(okm::nr_kill, -static_cast<okm_long>(j.h), 15 /* SIGTERM */);
+    // The signal that cannot be declined --- see openkal-linux for the reasoning:
+    // a unit contains programs the caller never held a handle to, so a request any
+    // member may ignore does not terminate the unit.
+    const okm_long r = okm::sys(okm::nr_kill, -static_cast<okm_long>(j.h), 9 /* SIGKILL */);
     return okm::failed(r) ? okm::translate(r) : kal_ok;
 }