M1.8a: process control (Signal/Suspend/Resume/Members) + shared-group runner; fix POSIX multi-child containment

Author: ZelAnton

CHANGELOG.md

@@ -24,11 +24,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Shell-free pipelines: `Command.Pipe(next)` builds a `Pipeline` that wires each stage's stdout into the next stage's stdin, running the whole chain in one kill-on-dispose group. The same verbs as a single command (`Run`/`RunUnit`/`OutputString`/`OutputBytes`/`ExitCode`/`Probe`/`Parse`/`TryParse`) plus `Pipeline.Timeout`/`CancelOn`. The exit status follows shell **pipefail** (the rightmost checked stage that did not exit 0 decides the result); `Command.UncheckedInPipe()` lets a stage fail without failing the pipeline.
 - Completed the `Command` convenience verbs: `RunUnit`/`ExitCode`/`Probe` now sit alongside `Run`/`OutputString`/`OutputBytes`, and every convenience verb has a `CancellationToken` overload.
 - `Supervisor` — keep a command alive with policy-driven restarts: `RestartPolicy` (`Always`/`OnCrash`/`Never`), exponential `Backoff` + `MaxBackoff` + `Jitter`, `MaxRestarts`, a failure-storm guard (`StormPause` + `FailureThreshold` + `FailureDecay`), and a `StopWhen` predicate, reporting a `SupervisionOutcome` (`FinalResult`/`Restarts`/`Stopped`/`StormPauses`) with `StopReason`. Runs through any `IProcessRunner` (`WithRunner`) so supervision is testable without spawning processes.
+- Process-tree control on `ProcessGroup`: `Signal` (the portable `Signal` type — `Term`/`Kill`/`Int`/`Hup`/`Quit`/`Usr1`/`Usr2`/`Other`; Windows delivers only `Kill`), `Suspend`/`Resume` (freeze/thaw the whole tree), `Members` (a pid snapshot), and `TerminateAll`.
+- `ProcessGroup` now implements `IProcessRunner` (`Start`/`OutputString`/`OutputBytes`): every run goes into that one shared kill-on-dispose group, so a fleet can share a container — e.g. `Supervisor.WithRunner(group)`. `ProcessGroup.Start` returns a `RunningProcess` whose lifetime the group owns.
 
 ### Changed
 -
 
 ### Fixed
--
+- POSIX containment now reaps **every** child of a multi-child group (e.g. a pipeline), not just the last. Each `posix_spawn` forms its own process group, so the group tracks all of them; previously only the most-recent pgid was killed, letting an earlier long-running stage linger until its natural exit.
 
 [Unreleased]: https://github.com/ZelAnton/ProcessKit-fSharp/commits/main

src/ProcessKit/Native.fs

@@ -365,6 +365,75 @@ module internal Native =
             GetExitCodeProcess(hProcess, &code) |> ignore
             Outcome.Exited(int code))
 
+    /// Hard-kill one Windows process (not its descendants — for that, terminate the whole Job).
+    let terminateWindowsProcess (hProcess: nativeint) =
+        TerminateProcess(hProcess, 1u) |> ignore
+
+    // Tree introspection / suspend-resume for the `process-control` surface.
+    [<Literal>]
+    let private JobObjectBasicProcessIdList = 3
+
+    [<Literal>]
+    let private PROCESS_SUSPEND_RESUME = 0x0800u
+
+    [<DllImport("kernel32.dll", SetLastError = true)>]
+    extern bool private QueryInformationJobObject(
+        nativeint hJob,
+        int infoClass,
+        nativeint lpInfo,
+        uint32 cbInfo,
+        uint32& returnLength
+    )
+
+    [<DllImport("kernel32.dll", SetLastError = true)>]
+    extern nativeint private OpenProcess(uint32 dwDesiredAccess, bool bInheritHandle, uint32 dwProcessId)
+
+    // NtSuspendProcess/NtResumeProcess freeze/thaw every thread of a process in one call. They are
+    // undocumented ntdll entry points but stable and the standard way to suspend a whole process;
+    // the documented alternative (snapshot every thread + SuspendThread) is far more code.
+    [<DllImport("ntdll.dll")>]
+    extern int private NtSuspendProcess(nativeint hProcess)
+
+    [<DllImport("ntdll.dll")>]
+    extern int private NtResumeProcess(nativeint hProcess)
+
+    /// Snapshot the pids assigned to a Job Object (the whole contained tree). A point-in-time view;
+    /// a process can exit immediately after. Caps at 1024 members (ample for a diagnostic snapshot).
+    let membersWindows (job: nativeint) : int list =
+        let capacity = 1024
+        let headerSize = 8 // two DWORDs: NumberOfAssignedProcesses, NumberOfProcessIdsInList
+        let size = headerSize + capacity * IntPtr.Size
+        let buffer = Marshal.AllocHGlobal size
+
+        try
+            let mutable returnLength = 0u
+
+            if QueryInformationJobObject(job, JobObjectBasicProcessIdList, buffer, uint32 size, &returnLength) then
+                let count = min (Marshal.ReadInt32(buffer, 4)) capacity
+
+                [ for i in 0 .. count - 1 -> int (Marshal.ReadIntPtr(buffer, headerSize + i * IntPtr.Size)) ]
+            else
+                []
+        finally
+            Marshal.FreeHGlobal buffer
+
+    // Suspend / resume every member process of a Job. Best-effort and not atomic: a process can
+    // spawn between the snapshot and the suspend; Windows keeps per-thread suspend counts, so nested
+    // suspends stack and need matching resumes (unlike the level-triggered POSIX SIGSTOP/SIGCONT).
+    let private forEachMemberHandle (job: nativeint) (action: nativeint -> unit) =
+        for pid in membersWindows job do
+            let handle = OpenProcess(PROCESS_SUSPEND_RESUME, false, uint32 pid)
+
+            if handle <> IntPtr.Zero then
+                action handle
+                CloseHandle handle |> ignore
+
+    let suspendWindows (job: nativeint) =
+        forEachMemberHandle job (fun handle -> NtSuspendProcess handle |> ignore)
+
+    let resumeWindows (job: nativeint) =
+        forEachMemberHandle job (fun handle -> NtResumeProcess handle |> ignore)
+
     let private buildWindowsEnvironment (command: Command) : nativeint =
         if not command.Config.ClearEnv && List.isEmpty command.Config.EnvOverrides then
             IntPtr.Zero
@@ -640,6 +709,32 @@ module internal Native =
     /// True while any process remains in the group (signal 0 probes existence).
     let processGroupAlive (pgid: int) = killpg (pgid, 0) = 0
 
+    // SIGSTOP / SIGCONT numbers differ between Linux and the BSD/macOS table (so do SIGUSR1/2);
+    // resolve them per-platform.
+    let private sigStop = if isMacOs then 17 else 19
+    let private sigCont = if isMacOs then 19 else 18
+
+    /// The raw POSIX signal number for a portable `Signal`, resolved for the current platform.
+    let signalNumber (signal: Signal) : int =
+        match signal with
+        | Signal.Term -> SIGTERM
+        | Signal.Kill -> SIGKILL
+        | Signal.Int -> 2
+        | Signal.Hup -> 1
+        | Signal.Quit -> 3
+        | Signal.Usr1 -> if isMacOs then 30 else 10
+        | Signal.Usr2 -> if isMacOs then 31 else 12
+        | Signal.Other n -> n
+
+    /// Broadcast a raw signal to a POSIX process group; `true` if the send was accepted.
+    let signalProcessGroup (pgid: int) (signalNum: int) : bool = killpg (pgid, signalNum) = 0
+
+    /// Freeze a POSIX process group (SIGSTOP).
+    let suspendProcessGroup (pgid: int) = killpg (pgid, sigStop) |> ignore
+
+    /// Thaw a POSIX process group (SIGCONT).
+    let resumeProcessGroup (pgid: int) = killpg (pgid, sigCont) |> ignore
+
     // Create a pipe whose ends are close-on-exec so a *different* concurrent spawn does not
     // inherit this run's pipe ends (which outlive the spawn). Linux sets it atomically with
     // pipe2(O_CLOEXEC); macOS lacks pipe2, and relies on POSIX_SPAWN_CLOEXEC_DEFAULT instead.