Kernels exit when their owner dies

[snimu]

Hundreds of leaked ipykernel processes (and ~1,900 stale prime-agent-kernel-* temp dirs) were draining batteries: every graceful shutdown path is clean, but when the owning process hard-dies (SIGKILL, crash, OOM — including root TUI sessions and killed test runners) the kernel's dispose never runs and it lives forever.

What changes:

• Kernels get JPY_PARENT_PID in their environment, arming ipykernel's built-in parent poller: direct spawns watch the Node owner; forked kernels watch their real parent, the forkserver (ipykernel's Unix poller distrusts a parent_handle that differs from getppid() and would fall back to a pid-1 reparent watch that subreapers never trigger — so the forked child passes the forkserver pid explicitly after the per-kernel env is applied, the trait default being frozen at template import).
• The forkserver script gains a daemon watchdog thread that polls os.getppid() and exits when its parent (the worker) disappears. A dead forkserver reparents its kernels, which trips their pollers — closing the chain on every platform, subreaper or not.
• Kernel and forkserver pids are registered in the orphan process journal on start and deregistered on confirmed teardown, so the supervisor's existing recovery sweep kills any survivors with verified process identity.

Follow-up (review feedback on pid-reuse): forked kernels are no longer signaled by bare pid from Node — after pid reuse that could kill an innocent process and write a wrong inactive journal record masking a sibling manager's active one. The forkserver (their parent, which waitpid-reaps them) now owns kill and liveness through new additive control-protocol messages, keyed by the fork request id rather than the pid: ids are unique and never reused, so a kill/alive can only ever act on the caller's own child incarnation, even if that child's pid was recycled by a later fork. The forkserver keeps a bounded id → (pid, alive) registry (FIFO, 4096 entries; evicted ids fail closed as unknown-pid), reaps children under a SIGCHLD discipline that blocks the signal in every thread but the main one and across both fork bookkeeping and the check+kill section (a parent signaling its own un-reaped child is POSIX-race-free; the forked child unblocks the inherited mask before running the kernel). The inactive orphan-journal write is restricted to the signaled outcome — the only one proving the pid still named our child at kill time; already-exited, unknown-pid, and errors leave the active record stale for the identity-verifying supervisor reaper, since the journal itself is pid-keyed and a wrong inactive write could mask a sibling manager's record.

Verified:

• Unit + protocol tests (macOS + Linux): direct/fork env carries the right parent pid; protocol kill round-trip, already-exited, unknown-fork-id never signals, liveness from the registry, kill outcomes truthful under concurrent child churn/reaping, a fast-exiting child never lands alive in the registry, evicting a still-alive entry stays fail-closed and reap-safe, dead-forkserver fallback never signals, journal gating (signaled → inactive; everything else → stale-active).
• Linux sandbox E2E (Ubuntu 24.04 VM, real prime-agent instance): forkserver path confirmed as Linux default; kill -9 of a real daemon worker took forkserver and kernel down in 2s; full feature smoke (persistent kernel state, %%bash, rlm subagent + agent messaging, direct-spawn path) clean with zero stray processes after daemon shutdown.
• Pid-reuse stress on that sandbox (kernel.pid_max=400, canary process recycled onto the dead kernel's pid before dispose): old code wrongly killed the canary 8/8 iterations; fixed code 0/8 with 8/8 recycles — the race reproduces deterministically and the fix eliminates it.
• Full suite on Linux (CI shape): failing-file set identical to the branch-point baseline (7 pre-existing env-specific files, 59 tests); branch adds 10 passing tests, zero regressions. npm run check clean.

Out of scope (ENG-5311, parallel PR): reaping pre-existing orphans and sweeping stale temp dirs via doctor.

LOC: +866 / -74 total (src +271/-74, tests +593/-0, changelog +2).

Fixes ENG-5310 (https://linear.app/primeintellect/issue/ENG-5310/kernels-must-not-outlive-their-owner-parent-death-watchdog-orphan)

Note

Make IPython kernels and forkserver exit when their owner dies

• Direct ipykernel spawns now set JPY_PARENT_PID so the kernel exits if the owning process dies. Forked kernels delegate kill and liveness queries through the forkserver, which also watches its own parent and terminates on owner death.
• ForkServer refactored to a request/reply protocol returning ForkedKernelHandle (with kill() and isAlive()) instead of a raw pid. This avoids pid-reuse races by routing all signaling and liveness through the forkserver with explicit outcomes.
• KernelManager adds generation-based guards (startGeneration, startStale()) to fence off stale concurrent start/shutdown interactions, and bounds liveness probes by startup budgets so hangs don't extend timeouts.
• Orphan-process journal records are written for child and forkserver pids on spawn, and marked inactive only on confirmed kills or observed exits. See index.ts and fork-server.ts.
• Also updates pricing constants for deepseek/deepseek-v4-flash and moonshotai/kimi-k2.6 in models.generated.ts.
• Behavioral Change: forkKernel now returns ForkedKernelHandle instead of a numeric pid; dispose() writes orphan journal inactive records only on confirmed kill or observed exit, leaving records active otherwise.

Changes since #1559 opened

• Changed the eviction policy in the _serve server loop to retain live child kernels beyond the historyBound by selectively evicting only entries with alive flag set to false, iterating through tracked children and removing exited entries until within the bound, eliminating removal of live entries and their pid-to-id routing mappings [967b2e9]
• Replaced test expecting eviction of alive entries with test asserting live entries are retained past historyBound and only exited entries are evicted [967b2e9]
• Updated pricing metadata for deepseek/deepseek-v4-flash model [14288cf]
• Updated pricing metadata for moonshotai/kimi-k2.6 model [14288cf]
• Modified liveness probe handling for forked kernels to treat timed-out fork server requests as unknown state rather than kernel death, and added serialization to prevent concurrent liveness probes [10aef5c]
• Added timeout indication capability to ForkServerUnavailable error class and configured fork server request timeouts to use it [10aef5c]
• Changed direct-spawn kernel cleanup to mark orphan process state as inactive only when a kill signal was successfully delivered [10aef5c]
• Added and updated tests to validate timeout handling in liveness probes, concurrent probe prevention, and direct-spawn cleanup behavior [10aef5c]
• Modified KernelManager.shutdown method to track cleanup execution with a boolean flag and determine ownership before performing cleanup operations [940bc35]
• Updated test assertions in kernel-parent-watchdog.test.ts and kernel-shutdown.test.ts to verify the new shutdown return value contract [940bc35]

^{Macroscope summarized 3393591.}

---

Note

High Risk
Changes how IPython kernels and the forkserver are signaled, reaped, and journaled for supervisor recovery. A bug here can leak processes or, on pid reuse, kill an unrelated process.

Overview
Stops leaked IPython kernels after a hard crash (SIGKILL/OOM) and closes a pid-reuse race on forked kernels.

Direct spawns set JPY_PARENT_PID so ipykernel’s parent poller exits with Node. The forkserver polls getppid() and dies with the worker; forked children watch the forkserver via parent_handle. Kernel and forkserver pids are journaled as orphans on spawn; inactive is written only on a confirmed kill or observed exit so a reused pid cannot mask a sibling’s record.

forkKernel now returns a ForkedKernelHandle. Kill and liveness are keyed by never-reused fork request ids (not raw process.kill), with SIGCHLD-blocked check+kill and a bounded registry that evicts only exited entries. KernelManager uses startGeneration so concurrent start/shutdown cannot tear down a successor kernel.

^{Reviewed by Cursor Bugbot for commit 10aef5c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3393591. Configure here.}