@crouton-kit/crouter 0.3.42 → 0.3.43

package/dist/core/__tests__/pid-zombie.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/pid-zombie.test.js

@@ -0,0 +1,42 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/pid-zombie.test.ts
+//
+// Regression cover for the zombie-broker revive bug: `kill(pid, 0)` reports a
+// ZOMBIE process (exited, awaiting reap by its parent) as perfectly alive —
+// its pid is still occupied in the process table. A broker's spawning process
+// that never gets to process its SIGCHLD (the real-world trigger: `bootRoot`'s
+// foreground attach session used to block its OWN event loop for the whole
+// session via a synchronous `spawnSync`, so it could never reap its detached
+// broker child in real time — see the async-spawn fix in runtime/spawn.ts)
+// leaves that broker a zombie indefinitely. The daemon's revive guard reads
+// liveness through `isPidAlive(pi_pid)` alone (`revive.ts`), so misreading a
+// zombie as alive wedges the relaunch forever. `isPidAlive` must classify a
+// genuine zombie as dead.
+//
+// Fabricates a REAL zombie: spawn a child with no exit listener, then starve
+// THIS process's own event loop with a synchronous busy-wait spanning the
+// child's exit — mirroring exactly how a blocking spawnSync parks the parent's
+// loop past a child's death, before any assertion ever runs.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { isPidAlive } from '../canvas/pid.js';
+test('isPidAlive reads a genuine zombie process as dead, not alive', () => {
+    const child = spawn('/bin/sh', ['-c', 'exit 0'], { detached: true, stdio: 'ignore' });
+    const pid = child.pid;
+    assert.ok(pid != null, 'child must have a pid');
+    child.unref(); // no exit listener attached — nothing reaps it while the loop is starved below
+    // Busy-wait SYNCHRONOUSLY (no `await`/timer — starving the event loop, not
+    // just delaying it) long enough for the child to exit and the kernel to
+    // mark it a zombie, before this process's SIGCHLD handling ever gets a turn.
+    const deadline = Date.now() + 400;
+    while (Date.now() < deadline) { /* starve the loop */ }
+    assert.equal(isPidAlive(pid), false, 'a zombie pid must read as dead, not alive');
+    // Best-effort cleanup: signaling an already-zombied pid is a harmless no-op
+    // (it's already dead) — the zombie self-clears once this test process exits
+    // and the orphan is reparented to init, same as every other fixture in this
+    // suite; nothing here relies on that timing for the assertion above.
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch { /* already gone */ }
+});

package/dist/core/canvas/pid.d.ts

@@ -1,6 +1,17 @@
-/** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
- *  0)` throws ESRCH when the process is gone; EPERM means it exists but isn't
- *  ours — still alive. A null/undefined pid (legacy / never-booted) reads dead. */
+/** True if a process with `pid` is currently alive (signal-0 probe) AND not a
+ *  zombie. `kill(pid, 0)` throws ESRCH when the process is gone; EPERM means
+ *  it exists but isn't ours — still alive (a foreign process is never OUR
+ *  zombie, so the `isZombie` check is skipped for that branch — see below). A
+ *  null/undefined pid (legacy / never-booted) reads dead.
+ *
+ *  The zombie check matters because EVERY broker this module supervises is
+ *  spawned `detached: true` by crtr itself (`headlessBrokerHost.launch`) — a
+ *  dead broker whose spawning process hasn't reaped it yet is a zombie, and
+ *  `kill(pid, 0)` alone reports it as alive, wedging the daemon's revive guard
+ *  (`isPidAlive(pi_pid)`, `revive.ts`) forever: the daemon never revives an
+ *  already-live-looking row, so a refreshed/crashed node whose broker zombied
+ *  out under a long-lived spawning process (see `isZombie`'s doc) never comes
+ *  back on its own. */
 export declare function isPidAlive(pid: number | null | undefined): boolean;
 /** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of

package/dist/core/canvas/pid.js

@@ -9,19 +9,56 @@
 // placement.ts, and crtrd.ts into one (Phase 3 review reuse MINOR-1).
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-/** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
- *  0)` throws ESRCH when the process is gone; EPERM means it exists but isn't
- *  ours — still alive. A null/undefined pid (legacy / never-booted) reads dead. */
+/** Is `pid` a ZOMBIE (exited, awaiting reap by its parent)? `kill(pid, 0)`
+ *  reports a zombie as a perfectly normal alive process — its PID is still
+ *  occupied in the process table — so callers relying on that signal-0 probe
+ *  alone (see `isPidAlive`) misread a dead broker as alive forever whenever
+ *  its spawning process never reaps it (crouton-labs zombie-broker bug: the
+ *  front door's foreground attach session parks its OWN event loop for the
+ *  whole session — see `bootRoot` in runtime/spawn.ts — so it can't process
+ *  the SIGCHLD that would otherwise reap its detached broker child in real
+ *  time). `ps -o stat=` reports a leading `Z` for a zombie on BOTH BSD ps
+ *  (macOS) and procps-ng (Linux), so one portable probe covers both platforms
+ *  without a Linux-only `/proc` special case. Best-effort: any probe failure
+ *  (spawn error, no matching row, non-zero exit) reads as NOT a zombie —
+ *  fail-open, matching this module's other guards; a probe failure must never
+ *  be misread as proof of death (a live pid IS alive; only a positive `Z`
+ *  read says otherwise). */
+function isZombie(pid) {
+    try {
+        const r = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return false;
+        return r.stdout.trim().charAt(0) === 'Z';
+    }
+    catch {
+        return false;
+    }
+}
+/** True if a process with `pid` is currently alive (signal-0 probe) AND not a
+ *  zombie. `kill(pid, 0)` throws ESRCH when the process is gone; EPERM means
+ *  it exists but isn't ours — still alive (a foreign process is never OUR
+ *  zombie, so the `isZombie` check is skipped for that branch — see below). A
+ *  null/undefined pid (legacy / never-booted) reads dead.
+ *
+ *  The zombie check matters because EVERY broker this module supervises is
+ *  spawned `detached: true` by crtr itself (`headlessBrokerHost.launch`) — a
+ *  dead broker whose spawning process hasn't reaped it yet is a zombie, and
+ *  `kill(pid, 0)` alone reports it as alive, wedging the daemon's revive guard
+ *  (`isPidAlive(pi_pid)`, `revive.ts`) forever: the daemon never revives an
+ *  already-live-looking row, so a refreshed/crashed node whose broker zombied
+ *  out under a long-lived spawning process (see `isZombie`'s doc) never comes
+ *  back on its own. */
 export function isPidAlive(pid) {
     if (pid == null)
         return false;
     try {
         process.kill(pid, 0);
-        return true;
     }
     catch (e) {
         return e.code === 'EPERM';
     }
+    return !isZombie(pid);
 }
 /** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of

package/dist/core/runtime/spawn.js

@@ -9,7 +9,7 @@
 //                terminal background worker by default; with `root`, an
 //                INDEPENDENT resident root (no subscription back to the spawner,
 //                provenance via spawned_by) brought forefront for direct driving.
-import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { readdirSync, existsSync } from 'node:fs';
 import { isAbsolute, resolve, join } from 'node:path';
 import { homedir } from 'node:os';
@@ -151,8 +151,23 @@ export async function bootRoot(opts) {
         throw new Error(`the front-door root broker ${meta.node_id} never bound its view socket — cannot attach.`);
     }
     const attachEnv = { ...process.env, ...viewerSplitEnv() };
-    const r = spawnSync('crtr', ['surface', 'attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
-    process.exit(r.status ?? 0);
+    // Async, NOT spawnSync: a synchronous spawn would park THIS process's own
+    // event loop for the whole attach session (which legitimately runs for
+    // hours) — starving it of the SIGCHLD delivery it needs to reap its OWN
+    // detached broker child (recorded above via `recordPid`). A refresh/crash
+    // mid-session would then leave that broker a zombie for as long as the user
+    // stays attached, which `isPidAlive` misread as "alive" and blocked the
+    // daemon's relaunch (the exact bug this fixes). An async spawn keeps this
+    // process's loop ticking throughout, so the broker's already-registered
+    // `exit` listener (`headlessBrokerHost.launch`) actually gets to run and
+    // reap it in real time; `stdio: 'inherit'` still hands the child the TTY
+    // directly, so this is a behavior-neutral swap for the foreground session.
+    const attachChild = spawn('crtr', ['surface', 'attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
+    const code = await new Promise((resolveCode) => {
+        attachChild.once('exit', (exitCode) => resolveCode(exitCode ?? 0));
+        attachChild.once('error', () => resolveCode(1));
+    });
+    process.exit(code);
 }
 /** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
  *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.42",
+  "version": "0.3.43",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",