@pareto4/pp-core 1.11.1 → 1.12.0

package/pp-core/bin/lib/prohibition-enforcement.cjs

@@ -67,6 +67,12 @@ const node_child_process_1 = require("node:child_process");
 const io = require("./io.cjs");
 const { output, error, ERROR_REASON } = io;
 const probe_core_cjs_1 = require("./probe-core.cjs");
+/** Bound on the reaper's own `ps` listing, so cleanup can never hang the check it follows. */
+const REAP_PS_TIMEOUT_MS = 5000;
+/** How long the reaper keeps re-sweeping for a late-arriving child before giving up. */
+const REAP_WINDOW_MS = 3000;
+/** Pause between reaper passes — long enough for a spawning child to become visible to `ps`. */
+const REAP_PASS_INTERVAL_MS = 250;
 /**
  * READ-BACK ADAPTER (#1278, plan 01-03): reconstruct a `CheckDescriptor` from the flat scalar keys
  * `projectProhibitions` emits onto a prohibition item (`check_kind` / `check_target` / `check_rule`,
@@ -360,6 +366,106 @@ const CHECK_MAX_BUFFER = 16 * 1024 * 1024;
 function posTimeout(timeoutMs, def) {
     return typeof timeoutMs === 'number' && timeoutMs > 0 ? timeoutMs : def;
 }
+/**
+ * Reap the test-runner descendants a timed-out `node --test` leaves behind.
+ *
+ * THE LEAK. Node's test runner isolates each file in its own process. When
+ * `execFileSync` times out it signals only the DIRECT child, so the runner dies
+ * and its test-file grandchildren are orphaned, reparented to init, and keep
+ * spinning at ~100% CPU forever.
+ *
+ * MEASURED, not theorised. On 2026-09-20 one developer machine carried 48 such
+ * orphans — oldest TWO DAYS, 1386% CPU across 15 cores, load average 70 — all of
+ * them `prohib-hang` grandchildren of this module. The leak is PER RUN: the count
+ * rose 47 to 48 during the few minutes it took to clean up, and 8 more
+ * accumulated across a single phase's suite runs. The second-order damage is the
+ * worse half: while the machine is saturated every timing-sensitive assertion in
+ * the suite is unreliable, so this sat underneath every local verification as a
+ * false-red generator.
+ *
+ * WHY SIGNALLING HARDER DOES NOT WORK, measured the same day against a spinning
+ * fixture: plain `execFileSync` left 1 spinning survivor, `killSignal: SIGKILL`
+ * left 1, and `--test-force-exit` left 1. The orphans are already detached from
+ * us, so no signal aimed at the runner can reach them. Only an active sweep did:
+ * the same fixture with this reaper left 0.
+ *
+ * `detached` + a negative-pid group kill is the usual answer and is NOT available
+ * here: `detached` is a `spawn` option, not a `spawnSync`/`execFileSync` one, and
+ * making this seam asynchronous would change its contract for every caller.
+ *
+ * SAFETY. This runs only after a timeout, kills only processes whose argv
+ * contains the exact target this call passed, and never itself. On Windows it is
+ * a no-op — `ps` is unavailable there and the pre-existing behaviour is left
+ * untouched rather than guessed at.
+ */
+function reapTimedOutTestRunner(target) {
+    if (process.platform === 'win32' || !target)
+        return;
+    // ONE PASS IS NOT ENOUGH, and that was measured the hard way. A single sweep
+    // reaped cleanly when this test ran ALONE, yet a full five-lane suite run still
+    // left 2 spinning orphans from the very same test. The runner and its per-file
+    // child are killed and spawned independently of us: on a loaded machine the
+    // child can appear in the process table AFTER a one-shot snapshot has already
+    // looked, so the sweep sees the dying runner and misses the survivor entirely.
+    // Sweeping until a pass comes up empty closes that window. Re-killing an
+    // already-dead pid is a no-op, so extra passes cost nothing but the listing.
+    const deadline = Date.now() + REAP_WINDOW_MS;
+    for (;;) {
+        let killedAny = false;
+        try {
+            const listing = (0, node_child_process_1.spawnSync)('ps', ['-eo', 'pid=,args='], {
+                encoding: 'utf-8',
+                timeout: REAP_PS_TIMEOUT_MS,
+                maxBuffer: CHECK_MAX_BUFFER,
+            });
+            const text = typeof listing.stdout === 'string' ? listing.stdout : '';
+            for (const line of text.split('\n')) {
+                if (!line.includes(target))
+                    continue;
+                const pid = Number(line.trim().split(/\s+/)[0]);
+                if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid)
+                    continue;
+                try {
+                    process.kill(pid, 'SIGKILL');
+                    killedAny = true;
+                }
+                catch {
+                    /* already gone, or not ours to signal — either way nothing to do */
+                }
+            }
+        }
+        catch {
+            /* the sweep is best-effort: never let cleanup fail the check it follows */
+            return;
+        }
+        // Empty pass: nothing of ours is left, and nothing is still arriving.
+        if (!killedAny)
+            return;
+        if (Date.now() >= deadline)
+            return;
+        sleepSync(REAP_PASS_INTERVAL_MS);
+    }
+}
+/**
+ * Block for `ms`. The seam this runs in is synchronous for every caller, so the
+ * reaper cannot await — and a busy-wait here would compete for the very CPU the
+ * orphans are saturating, which is the condition this code exists to end.
+ */
+function sleepSync(ms) {
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    catch {
+        /* SharedArrayBuffer unavailable — skip the pause rather than spin a core */
+    }
+}
+/** Did this thrown error come from the bound rather than from the test failing? */
+function isTimeoutError(e) {
+    if (!e || typeof e !== 'object')
+        return false;
+    const err = e;
+    return err.code === 'ETIMEDOUT' || typeof err.signal === 'string';
+}
 function defaultRunCheck(check, cwd, timeoutMs) {
     try {
         if (check.kind === 'node-test') {
@@ -380,6 +486,9 @@ function defaultRunCheck(check, cwd, timeoutMs) {
                 // summary). Parse what we have: a real failure or timeout -> not a non-vacuous pass -> false.
                 const stdout = e && typeof e === 'object' && 'stdout' in e ? e.stdout : '';
                 out = typeof stdout === 'string' ? stdout : '';
+                // The bound fired: the runner is dead but its per-file children are not.
+                if (isTimeoutError(e))
+                    reapTimedOutTestRunner(check.target);
             }
             return { passed: isNonVacuousNodeTestPass(out, check.target) };
         }
@@ -510,6 +619,9 @@ function defaultProveFailFirst(check, cwd, timeoutMs) {
                 // is on stdout. Parse what we have: a real failure here is the PROOF the test is fail-first.
                 const stdout = e && typeof e === 'object' && 'stdout' in e ? e.stdout : '';
                 out = typeof stdout === 'string' ? stdout : '';
+                // Same bound, same orphans: this site leaked identically to the positive arm.
+                if (isTimeoutError(e))
+                    reapTimedOutTestRunner(check.target);
             }
             return { provenFailFirst: isNonVacuousNodeTestRed(out, check.target), method: 'violation-fixture' };
         }