ai-or-die 0.1.76 → 0.1.77

package/bin/supervisor.js

@@ -5,6 +5,7 @@
 const { spawn } = require('child_process');
 const path = require('path');
 const { RESTART_EXIT_CODE } = require('../src/restart-manager');
+const jobGuard = require('../src/job-guard');
 
 // ---------------------------------------------------------------------------
 // Tunables — all overridable via env vars so the regression test can shrink
@@ -14,7 +15,12 @@ const { RESTART_EXIT_CODE } = require('../src/restart-manager');
 
 const RESTART_DELAY_MS         = parseInt(process.env.RESTART_DELAY_MS, 10)         || 1000;     // clean RESTART_EXIT_CODE respawn
 const CRASH_RESTART_DELAY_MS   = parseInt(process.env.CRASH_RESTART_DELAY_MS, 10)   || 3000;     // normal crash respawn
-const SHUTDOWN_TIMEOUT_MS      = parseInt(process.env.SHUTDOWN_TIMEOUT_MS, 10)      || 10000;    // SIGINT/SIGTERM hard-kill fallback
+// Must stay strictly GREATER than the server's own 15s force-exit budget
+// (src/server.js handleShutdown) so a hung graceful shutdown lets the server
+// finish (or self-force-exit) its own ordered teardown — including killing its
+// PTY trees — before the supervisor hard-kills it. A supervisor SIGKILL that
+// preempted the server would orphan the server's PTY/grandchild tree.
+const SHUTDOWN_TIMEOUT_MS      = parseInt(process.env.SHUTDOWN_TIMEOUT_MS, 10)      || 20000;    // SIGINT/SIGTERM hard-kill fallback
 
 // Tier 1 — tight crash loop. 3 crashes in 30 s historically tripped a hard
 // process.exit(1). The fix replaces that with an extended restart delay
@@ -49,6 +55,12 @@ let spawnCount = 0;
 let crashTimestamps = [];
 let pendingRestartTimer = null;
 
+// Windows Job Object guard. Set up once at startup (below, before the first spawn).
+// `jobGuardHandle` is held for the supervisor's entire life and intentionally NEVER
+// closed by us — process death closes it, which is exactly what fires KILL_ON_JOB_CLOSE.
+let jobGuardHandle = null;
+let jobGuardActive = false;
+
 // Queued IPC message delivered to the NEXT spawned child once its IPC channel
 // is open. Used to forward tier-2 escalation downstream so the in-process
 // server can surface it to the browser ("supervisor is throttling restarts").
@@ -121,6 +133,9 @@ function startServer() {
     env: {
       ...process.env,
       SUPERVISED: '1',
+      // Tell the server whether the kill-on-close job guard is active, so it can
+      // surface the unprotected state in /api/diagnostics (jobGuard:false).
+      AOD_JOB_GUARD: jobGuardActive ? '1' : '0',
       ...(isRestart ? { AOD_SUPERVISOR_RESTART: '1' } : {})
     }
   });
@@ -252,4 +267,39 @@ process.on('message', (msg) => {
   if (msg && msg.type === 'shutdown') shutdownGracefully();
 });
 
+// Establish the Windows Job Object guard BEFORE the first spawn so the server and its
+// entire future tree (PTYs, the CLI's node/bun MCP grandchildren) auto-join the job.
+// AssignProcessToJobObject is forward-looking: future children join, so the supervisor
+// must be assigned while it still has no descendants — i.e. before startServer(). When
+// the supervisor dies for ANY reason (Ctrl+C, crash, taskkill /F, console close), the OS
+// closes the in-process handle and the kernel atomically terminates the whole job.
+// No-op on non-Windows / when koffi is unavailable (jobGuardActive stays false →
+// best-effort teardown, surfaced as jobGuard:false in /api/diagnostics).
+function setupJobGuard() {
+  try {
+    if (!jobGuard.isAvailable()) {
+      if (process.platform === 'win32') {
+        console.warn('[supervisor] ⚠ process-guard: koffi unavailable; using best-effort teardown. ' +
+          'Child node/bun processes may survive an uncatchable kill (taskkill /F).');
+      }
+      return;
+    }
+    jobGuardHandle = jobGuard.createKillOnCloseJob();
+    if (jobGuardHandle && jobGuard.assignSelf(jobGuardHandle)) {
+      jobGuardActive = true;
+      console.log('[supervisor] process-guard: kill-on-close job active — the whole tree dies with the supervisor.');
+    } else {
+      jobGuardHandle = null;
+      console.warn('[supervisor] ⚠ process-guard: could not create/assign the job object ' +
+        '(outer job UI limits / EDR / silo?); using best-effort teardown. ' +
+        'Child node/bun processes may survive an uncatchable kill.');
+    }
+  } catch (e) {
+    jobGuardHandle = null;
+    jobGuardActive = false;
+    console.warn('[supervisor] ⚠ process-guard: setup failed (' + (e && e.message) + '); continuing without it.');
+  }
+}
+
+setupJobGuard();
 startServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.76",
+  "version": "0.1.77",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {
@@ -47,6 +47,7 @@
     "cors": "^2.8.5",
     "express": "^4.19.2",
     "fuzzysort": "^3.1.0",
+    "koffi": "^3.0.2",
     "open": "^10.1.0",
     "selfsigned": "^2.4.1",
     "sherpa-onnx-node": "^1.12.24",

package/src/base-bridge.js

@@ -3,6 +3,8 @@ const { execFile } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
+const jobGuard = require('./job-guard');
+const { killProcessTreeSync } = require('./utils/process-tree');
 
 /** Chunk size for PTY writes — safely below ConPTY ~16KB kernel buffer */
 const PTY_WRITE_CHUNK_SIZE = 4096;
@@ -314,6 +316,11 @@ class BaseBridge {
 
       this.sessions.set(sessionId, session);
 
+      // Windows: enclose the PTY in its own kill-on-close Job Object now, before the CLI
+      // boots, so the CLI's future node/bun MCP grandchildren auto-join and can be reaped
+      // atomically on stopSession. No-op elsewhere.
+      this._attachPtyJob(session, ptyProcess);
+
       // Spawn watchdog: if no data, exit, or error arrives within 30s, treat as failure
       let receivedLifeSign = false;
       const ptyStartedAt = Date.now();
@@ -334,6 +341,14 @@ class BaseBridge {
           // the kill() below succeeds.
           this._disposePtyDisposables(session, sessionId);
           try { ptyProcess.kill(); } catch (e) { /* ignore */ }
+          // Reap the PTY subtree (Windows job close / POSIX group kill) so a hung-at-startup
+          // shell + any children it already spawned don't leak.
+          {
+            const jobClosed = this._disposePtyJob(session);
+            if (!jobClosed && ptyProcess && ptyProcess.pid) {
+              try { killProcessTreeSync(ptyProcess.pid); } catch (_) { /* best-effort */ }
+            }
+          }
           onError(new Error(`${this.toolName} process did not respond within ${SPAWN_TIMEOUT_MS / 1000} seconds. The command may not be installed or may have hung during startup.`));
         }
       }, SPAWN_TIMEOUT_MS);
@@ -390,6 +405,10 @@ class BaseBridge {
         // still hold references to the data-buffer closures. Skip onExit
         // self-disposal (node-pty already removed it on fire).
         this._disposePtyDisposables(session, sessionId);
+        // The PTY exited on its own, but the CLI's node/bun grandchildren may still be
+        // alive (node-pty doesn't walk the console process list). Closing the per-PTY
+        // kill-on-close job reaps them and frees the handle (Windows; no-op on POSIX).
+        this._disposePtyJob(session);
         if (this.sessions.has(sessionId)) {
           session.active = false;
           this.sessions.delete(sessionId);
@@ -444,6 +463,14 @@ class BaseBridge {
         // the shell is alive but unreadable) doesn't leak as a zombie process /
         // FD — mirrors the spawn-watchdog teardown. Harmless if already dead.
         try { ptyProcess.kill(); } catch (e) { /* ignore — may already be dead */ }
+        // Reap the subtree (Windows job close / POSIX group kill) so the shell's
+        // node/bun grandchildren don't outlive the failed session.
+        {
+          const jobClosed = this._disposePtyJob(session);
+          if (!jobClosed && ptyProcess && ptyProcess.pid) {
+            try { killProcessTreeSync(ptyProcess.pid); } catch (_) { /* best-effort */ }
+          }
+        }
         if (this.sessions.has(sessionId)) {
           session.active = false;
           this.sessions.delete(sessionId);
@@ -584,6 +611,53 @@ class BaseBridge {
     }
   }
 
+  /**
+   * Windows only: put a freshly-spawned PTY in its OWN kill-on-close Job Object so the
+   * PTY and the CLI's node/bun MCP grandchildren can be torn down atomically per session
+   * (see _disposePtyJob). Assigned right after spawn — before the CLI boots and spawns its
+   * children — so those future grandchildren auto-join the job. No-op on POSIX / when the
+   * job guard is unavailable (then teardown falls back to process-group / taskkill).
+   * Defence in depth: the PTY is also in the supervisor-level job, so supervisor death
+   * reaps it regardless.
+   * @private
+   */
+  _attachPtyJob(session, ptyProcess) {
+    if (process.platform !== 'win32' || !session) return;
+    try {
+      if (!jobGuard.isAvailable()) return;
+      const pid = ptyProcess && ptyProcess.pid;
+      if (!pid) return;
+      // Defensive: if a handle already exists for this session (re-entrant call), close it
+      // first so we never overwrite a live kernel handle and leak it.
+      if (session.jobHandle) this._disposePtyJob(session);
+      const handle = jobGuard.createKillOnCloseJob();
+      if (!handle) return;
+      if (jobGuard.assignPid(handle, pid)) {
+        session.jobHandle = handle;
+      } else {
+        // Assign failed (already-orphaned / access denied) — closing an empty job is harmless.
+        jobGuard.closeJob(handle);
+      }
+    } catch (_) { /* best-effort; never break session start */ }
+  }
+
+  /**
+   * Close a session's per-PTY job handle. On Windows this is the deterministic teardown:
+   * KILL_ON_JOB_CLOSE terminates the PTY + every descendant still in the job (the node/bun
+   * grandchildren). Also frees the kernel handle. Idempotent; no-op when no handle exists.
+   * Returns true when a job was actually closed (the subtree is reaped deterministically),
+   * false otherwise — callers use this to decide whether to escalate to the best-effort
+   * fallback (taskkill /T /F on Windows / process-group kill on POSIX) for the degraded
+   * path where no job exists (koffi unavailable: SEA binary, EDR/CLM-blocked, or POSIX).
+   * @private
+   */
+  _disposePtyJob(session) {
+    if (!session || !session.jobHandle) return false;
+    const h = session.jobHandle;
+    session.jobHandle = null;
+    try { return !!jobGuard.closeJob(h); } catch (_) { return false; }
+  }
+
   async stopSession(sessionId) {
     const session = this.sessions.get(sessionId);
     if (!session) {
@@ -608,13 +682,20 @@ class BaseBridge {
     // runs.
     this._disposePtyDisposables(session, sessionId);
 
-    if (!session.process) return;
+    // No live process to wait on — close the per-PTY job (reaps any lingering grandchildren
+    // and frees the kernel handle) before returning, so this path can't leak the handle.
+    if (!session.process) { this._disposePtyJob(session); return; }
+
+    // Capture the pid before kill(): node-pty may clear it on exit, and we need it
+    // for the POSIX process-group escalation below.
+    const ptyPid = session.process.pid;
 
     // Return a promise that resolves when the PTY process actually exits
     // (or after a bounded timeout), so callers can await clean shutdown.
     return new Promise((resolve) => {
       let settled = false;
       let waitDisposable = null;
+      let exited = false;
 
       const cleanup = () => {
         if (settled) return;
@@ -628,11 +709,24 @@ class BaseBridge {
         if (waitDisposable && typeof waitDisposable.dispose === 'function') {
           try { waitDisposable.dispose(); } catch (_) { /* ignore */ }
         }
+        // Deterministic subtree teardown. On Windows with the job guard, closing the
+        // per-PTY kill-on-close job terminates the shell + its node/bun grandchildren and
+        // frees the handle — what node-pty's own kill() cannot do. When no job was closed
+        // (degraded: koffi unavailable in a SEA binary / EDR-blocked, or POSIX) AND the PTY
+        // did not exit on its own, escalate to the best-effort fallback: taskkill /T /F on
+        // Windows, or a process-group kill on POSIX (node-pty PTYs are session leaders). We
+        // skip the fallback after a clean exit to sidestep any pid/pgid-reuse window.
+        {
+          const jobClosed = this._disposePtyJob(session);
+          if (!jobClosed && !exited && ptyPid) {
+            try { killProcessTreeSync(ptyPid); } catch (_) { /* best-effort */ }
+          }
+        }
         resolve();
       };
 
       try {
-        const handle = session.process.onExit(() => cleanup());
+        const handle = session.process.onExit(() => { exited = true; cleanup(); });
         // node-pty returns an IDisposable; older mocks may return undefined.
         if (handle && typeof handle.dispose === 'function') waitDisposable = handle;
       } catch (_) {
@@ -672,6 +766,25 @@ class BaseBridge {
       await this.stopSession(sessionId);
     }
   }
+
+  /**
+   * Synchronous, best-effort reap of EVERY live PTY subtree this bridge owns. For the
+   * uncaughtException and supervisor-death (IPC disconnect) paths, where we are about to
+   * exit and cannot await async teardown. Windows: close each per-PTY kill-on-close job
+   * (terminates the shell + node/bun grandchildren). POSIX: process-group kill of each PTY.
+   * Never throws.
+   */
+  killAllSubtreesSync() {
+    for (const [, session] of this.sessions) {
+      let jobClosed = false;
+      try { jobClosed = this._disposePtyJob(session); } catch (_) { jobClosed = false; }
+      // Degraded fallback (no job closed): taskkill /T /F on Windows, process-group kill
+      // on POSIX. When the job WAS closed the kernel already reaped the subtree.
+      if (!jobClosed && session && session.process && session.process.pid) {
+        try { killProcessTreeSync(session.process.pid); } catch (_) { /* ignore */ }
+      }
+    }
+  }
 }
 
 module.exports = BaseBridge;

package/src/job-guard.js

@@ -0,0 +1,249 @@
+'use strict';
+
+// Windows Job Object guard — deterministic process-tree teardown.
+//
+// The core mechanism for "no zombie node/bun processes": a Win32 Job Object with
+// JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE. When the last handle to such a job closes
+// (the holding process dies for ANY reason — Ctrl+C, crash, taskkill /F, console
+// close), the kernel terminates EVERY process in the job atomically, with no user
+// code running. This is the only Windows mechanism that survives an uncatchable kill.
+//
+// Two uses (see docs/specs/process-shutdown.md, ADR-00NN):
+//   1. Supervisor-level job: bin/supervisor.js creates a kill-on-close job and assigns
+//      ITSELF before forking the server. AssignProcessToJobObject is forward-looking, so
+//      every future descendant (server, PTYs, the CLI's node/bun MCP grandchildren) joins
+//      the job. Supervisor death closes the in-process handle → the whole tree dies. The
+//      job persists across server restarts (only supervisor death closes the handle), so
+//      the legitimate exit-75 memory restart is unaffected.
+//   2. Per-PTY nested job: src/base-bridge.js puts each PTY in its own kill-on-close job;
+//      closing that handle on stopSession atomically kills the PTY + its grandchildren —
+//      deterministic per-session teardown that also satisfies "restart independently".
+//
+// Held IN-PROCESS via the koffi FFI (not an external helper, which would be a single
+// point of failure, and not PowerShell, whose Add-Type→csc.exe is blocked by CLM/WDAC/
+// AMSI on the hardened corporate boxes that are the primary audience). The job's
+// BREAKAWAY_OK flag is deliberately left OFF so a child requesting CREATE_BREAKAWAY_FROM_JOB
+// is kept in the job rather than escaping it.
+//
+// Windows-only by design; a no-op on macOS/Linux and whenever koffi is unavailable
+// (e.g. under Bun, or a locked-down box). Never throws into the caller — the guard must
+// never break startup; failure degrades to best-effort taskkill (jobGuard:false).
+
+const IS_WIN = process.platform === 'win32';
+
+// JOBOBJECTINFOCLASS
+const JobObjectExtendedLimitInformation = 9;
+// JOBOBJECT_BASIC_LIMIT_INFORMATION.LimitFlags
+const JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000;
+// OpenProcess access rights needed to assign a foreign pid to a job
+const PROCESS_TERMINATE = 0x0001;
+const PROCESS_SET_QUOTA = 0x0100;
+
+let _koffi = null;
+let _api = null;
+let _loadError = null;
+
+// Lazily bind kernel32 via koffi. Returns the bound API or null (cached).
+function _ensureApi() {
+  if (_api || _loadError) return _api;
+  if (!IS_WIN) { _loadError = new Error('not win32'); return null; }
+  try {
+    _koffi = require('koffi');
+
+    const JOBOBJECT_BASIC_LIMIT_INFORMATION = _koffi.struct('JOBOBJECT_BASIC_LIMIT_INFORMATION', {
+      PerProcessUserTimeLimit: 'int64',
+      PerJobUserTimeLimit: 'int64',
+      LimitFlags: 'uint32',
+      MinimumWorkingSetSize: 'size_t',
+      MaximumWorkingSetSize: 'size_t',
+      ActiveProcessLimit: 'uint32',
+      Affinity: 'size_t',
+      PriorityClass: 'uint32',
+      SchedulingClass: 'uint32',
+    });
+    const IO_COUNTERS = _koffi.struct('IO_COUNTERS', {
+      ReadOperationCount: 'uint64',
+      WriteOperationCount: 'uint64',
+      OtherOperationCount: 'uint64',
+      ReadTransferCount: 'uint64',
+      WriteTransferCount: 'uint64',
+      OtherTransferCount: 'uint64',
+    });
+    const JOBOBJECT_EXTENDED_LIMIT_INFORMATION = _koffi.struct('JOBOBJECT_EXTENDED_LIMIT_INFORMATION', {
+      BasicLimitInformation: JOBOBJECT_BASIC_LIMIT_INFORMATION,
+      IoInfo: IO_COUNTERS,
+      ProcessMemoryLimit: 'size_t',
+      JobMemoryLimit: 'size_t',
+      PeakProcessMemoryUsed: 'size_t',
+      PeakJobMemoryUsed: 'size_t',
+    });
+
+    const k = _koffi.load('kernel32.dll');
+    _api = {
+      sizeofExtLimit: _koffi.sizeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION),
+      CreateJobObjectW: k.func('void* __stdcall CreateJobObjectW(void* lpJobAttributes, void* lpName)'),
+      // The struct is registered in koffi's type registry under its name, so the C
+      // prototype can reference it by that name (passed by pointer → marshaled from a JS object).
+      SetInformationJobObject: k.func('int __stdcall SetInformationJobObject(void* hJob, int JobObjectInformationClass, ' +
+        'JOBOBJECT_EXTENDED_LIMIT_INFORMATION* lpJobObjectInformation, uint32 cbJobObjectInformationLength)'),
+      AssignProcessToJobObject: k.func('int __stdcall AssignProcessToJobObject(void* hJob, void* hProcess)'),
+      OpenProcess: k.func('void* __stdcall OpenProcess(uint32 dwDesiredAccess, int bInheritHandle, uint32 dwProcessId)'),
+      GetCurrentProcess: k.func('void* __stdcall GetCurrentProcess()'),
+      CloseHandle: k.func('int __stdcall CloseHandle(void* hObject)'),
+      GetLastError: k.func('uint32 __stdcall GetLastError()'),
+    };
+  } catch (err) {
+    _loadError = err;
+    _api = null;
+  }
+  return _api;
+}
+
+// True only when the koffi-backed Win32 binding is usable on this platform.
+// `AOD_DISABLE_JOB_GUARD=1` forces it off (operator escape hatch if koffi/the FFI ever
+// misbehaves, and the hook that lets tests exercise the best-effort degraded teardown).
+// In the SEA single-file binary koffi is externalized out of the bundle and there is no
+// node_modules, so it can never load — short-circuit to degraded mode without attempting
+// the require (keeps the PTY-start hot path free of a doomed module lookup).
+function isAvailable() {
+  if (process.env.AOD_DISABLE_JOB_GUARD === '1') return false;
+  if (typeof global !== 'undefined' && global.__SEA_MODE__) return false;
+  return !!_ensureApi();
+}
+
+// Explicit NULL-handle predicate. koffi 3.x returns JS `null` for a NULL pointer and a
+// BigInt for a valid HANDLE (verified on koffi 3.0.2), so a bare `!h` already works; this
+// guards the common shapes explicitly so a future koffi representation of NULL (0 / 0n /
+// undefined) can't slip an invalid handle into a WinAPI call.
+function _isNullHandle(h) {
+  return h === null || h === undefined || h === 0 || h === 0n;
+}
+
+// Create a job object with KILL_ON_JOB_CLOSE set (BREAKAWAY_OK deliberately OFF).
+// Returns the job handle (opaque, pass back to assign*/closeJob) or null on any failure.
+function createKillOnCloseJob() {
+  const api = _ensureApi();
+  if (!api) return null;
+  let job = null;
+  try {
+    job = api.CreateJobObjectW(null, null);
+    if (_isNullHandle(job)) return null;
+    const info = {
+      BasicLimitInformation: {
+        PerProcessUserTimeLimit: 0n,
+        PerJobUserTimeLimit: 0n,
+        LimitFlags: JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
+        MinimumWorkingSetSize: 0,
+        MaximumWorkingSetSize: 0,
+        ActiveProcessLimit: 0,
+        Affinity: 0,
+        PriorityClass: 0,
+        SchedulingClass: 0,
+      },
+      IoInfo: {
+        ReadOperationCount: 0n, WriteOperationCount: 0n, OtherOperationCount: 0n,
+        ReadTransferCount: 0n, WriteTransferCount: 0n, OtherTransferCount: 0n,
+      },
+      ProcessMemoryLimit: 0,
+      JobMemoryLimit: 0,
+      PeakProcessMemoryUsed: 0,
+      PeakJobMemoryUsed: 0,
+    };
+    const ok = api.SetInformationJobObject(job, JobObjectExtendedLimitInformation, info, api.sizeofExtLimit);
+    if (!ok) {
+      // Could not arm kill-on-close — a job without it is useless (worse: it would
+      // hold processes without ever reaping them). Close and fail closed to null.
+      try { api.CloseHandle(job); } catch (_) { /* ignore */ }
+      return null;
+    }
+    return job;
+  } catch (_) {
+    if (job) { try { api.CloseHandle(job); } catch (__) { /* ignore */ } }
+    return null;
+  }
+}
+
+// Assign the CURRENT process to the job (used by the supervisor before forking).
+// Returns true on success. After this, all future descendants auto-join the job.
+function assignSelf(job) {
+  const api = _ensureApi();
+  if (!api || _isNullHandle(job)) return false;
+  try {
+    const self = api.GetCurrentProcess(); // pseudo-handle (-1); valid for AssignProcessToJobObject
+    return !!api.AssignProcessToJobObject(job, self);
+  } catch (_) {
+    return false;
+  }
+}
+
+// Assign a foreign process (by pid) to the job (used per-PTY). Opens a scoped handle
+// with exactly the rights needed, assigns, then closes that process handle (NOT the job).
+// Returns true on success.
+//
+// PID-reuse safety: callers must pass the pid of a process they KNOW is currently alive
+// and call this synchronously after spawning it (base-bridge._attachPtyJob runs in the same
+// synchronous tick as node-pty's spawn() that produced the pid), so there is no async window
+// in which the pid could be recycled before OpenProcess. Do NOT call this with a pid that
+// may have already exited.
+function assignPid(job, pid) {
+  const api = _ensureApi();
+  if (!api || _isNullHandle(job) || !pid) return false;
+  let h = null;
+  try {
+    h = api.OpenProcess(PROCESS_TERMINATE | PROCESS_SET_QUOTA, 0, pid >>> 0);
+    if (_isNullHandle(h)) return false;
+    return !!api.AssignProcessToJobObject(job, h);
+  } catch (_) {
+    return false;
+  } finally {
+    if (!_isNullHandle(h)) { try { api.CloseHandle(h); } catch (_) { /* ignore */ } }
+  }
+}
+
+// Close a job handle. For a per-PTY kill-on-close job this is the teardown trigger:
+// it terminates every process still in the job. Idempotent-safe to call with null.
+// NEVER call this on the supervisor-level job (its close = kill the whole tree); the
+// supervisor holds it for life and lets process death close it.
+function closeJob(job) {
+  const api = _ensureApi();
+  if (!api || _isNullHandle(job)) return false;
+  try {
+    return !!api.CloseHandle(job);
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = {
+  isAvailable,
+  createKillOnCloseJob,
+  assignSelf,
+  assignPid,
+  closeJob,
+  // exposed for diagnostics/tests
+  _loadError: () => _loadError,
+};
+
+// --- self-test: `node src/job-guard.js` ------------------------------------------
+// Proves the koffi bindings + struct marshaling work end to end on this host:
+// create a kill-on-close job, assign a spawned child, close the job, assert the child dies.
+if (require.main === module) {
+  if (!IS_WIN) { console.log('job-guard self-test: non-win32, no-op OK'); process.exit(0); }
+  const { spawn } = require('child_process');
+  console.log('koffi available:', isAvailable(), 'loadError:', _loadError && _loadError.message);
+  const job = createKillOnCloseJob();
+  console.log('createKillOnCloseJob ->', job ? 'OK' : 'FAIL');
+  if (!job) process.exit(1);
+  // Long-lived child that does nothing but stay alive.
+  const child = spawn(process.execPath, ['-e', 'setInterval(()=>{}, 1e9)'], { stdio: 'ignore' });
+  console.log('spawned child pid', child.pid);
+  setTimeout(() => {
+    const assigned = assignPid(job, child.pid);
+    console.log('assignPid ->', assigned ? 'OK' : 'FAIL');
+    closeJob(job);
+    console.log('closeJob called; waiting to see if child dies...');
+    let exited = false;
+    child.on('exit', (code, sig) => { exited = true; console.log(`child exited code=${code} sig=${sig} -> KILL-ON-CLOSE OK`); process.exit(0); });
+    setTimeout(() => { if (!exited) { console.log('child STILL ALIVE -> FAIL'); try { child.kill(); } catch (_) {} process.exit(2); } }, 2000);
+  }, 300);
+}

package/src/server.js

@@ -384,6 +384,10 @@ class ClaudeCodeWebServer {
       } catch (saveErr) {
         console.error('Failed to save sessions on crash:', saveErr);
       }
+      // Reap PTY subtrees so the CLI's node/bun grandchildren don't outlive this crashed
+      // server. Synchronous (the event loop is unsafe here). Windows closes each per-PTY
+      // job; POSIX group-kills. Best-effort; never rethrows.
+      try { this._reapAllPtySubtreesSync(); } catch (_) { /* ignore */ }
       process.exit(1);
     });
     process.on('unhandledRejection', (reason) => {
@@ -401,10 +405,21 @@ class ClaudeCodeWebServer {
         this.handleShutdown();
       }
     });
-    // If the supervisor crashes, continue running standalone
+    // If the supervisor's IPC channel drops, the supervisor died. Per the
+    // "everything dies when the main process dies" contract, this server must NOT
+    // keep running standalone (the old behavior) — it tears down its own PTY trees
+    // (incl. the CLI's node/bun grandchildren) and shuts down.
     process.on('disconnect', () => {
-      console.warn('IPC channel disconnected (supervisor may have crashed). Continuing standalone.');
-      this.supervised = false;
+      // Expected channel close: a graceful shutdown / memory-restart we initiated is
+      // already in flight (the supervisor sent {type:'shutdown'} or we exited 75). No-op.
+      if (this.isShuttingDown) return;
+      console.warn('IPC channel disconnected (supervisor died). Tearing down this server and its process tree.');
+      // Reap PTY subtrees synchronously FIRST so the node/bun grandchildren die immediately,
+      // even if the ordered handleShutdown below is slow. On Windows with the job guard
+      // active the kernel has usually already killed us; this is the cross-platform /
+      // degraded-mode backstop.
+      try { this._reapAllPtySubtreesSync(); } catch (_) { /* best-effort */ }
+      this.handleShutdown(0);
     });
   }
   
@@ -3937,6 +3952,24 @@ class ClaudeCodeWebServer {
     return bridges[agentType] || null;
   }
 
+  /**
+   * Synchronously reap every PTY subtree across all bridges. For the crash / supervisor-
+   * death paths where we are exiting and cannot await async teardown. Windows closes each
+   * per-PTY kill-on-close job (terminates the shell + node/bun grandchildren); POSIX
+   * process-group kills. Best-effort; never throws.
+   */
+  _reapAllPtySubtreesSync() {
+    const bridges = [
+      this.claudeBridge, this.codexBridge, this.copilotBridge,
+      this.geminiBridge, this.terminalBridge,
+    ];
+    for (const b of bridges) {
+      if (b && typeof b.killAllSubtreesSync === 'function') {
+        try { b.killAllSubtreesSync(); } catch (_) { /* ignore */ }
+      }
+    }
+  }
+
   async startToolSession(wsId, toolName, bridge, options, cols, rows) {
     const wsInfo = this.webSocketConnections.get(wsId);
     if (!wsInfo) {
@@ -5226,6 +5259,15 @@ class ClaudeCodeWebServer {
           .filter(s => s._voiceUploadTimestamps && s._voiceUploadTimestamps.length).length,
         activity_broadcast_timestamps: (this.activityBroadcastTimestamps && this.activityBroadcastTimestamps.size) || 0,
       },
+      // Deterministic-shutdown guard status. On win32, job_guard_active reflects whether
+      // the supervisor established the kill-on-close Job Object (false ⇒ degraded:
+      // EDR/CLM/koffi unavailable ⇒ best-effort taskkill teardown). null off win32 (the
+      // job mechanism is Windows-only; POSIX uses process-group teardown). See
+      // docs/specs/process-shutdown.md.
+      process_guard: {
+        job_guard_active: process.platform === 'win32' ? (process.env.AOD_JOB_GUARD === '1') : null,
+        supervised: !!this.supervised,
+      },
       // DISK-02/03: cached disk usage sample (60 s TTL, never blocks the
       // event loop). Populated by _sampleDiskUsage() — see method
       // comment for the time-budget contract.

package/src/utils/process-tree.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// Cross-platform best-effort process-tree teardown.
+//
+// This is the FALLBACK layer, used when the deterministic mechanism is unavailable:
+//   - Windows: the per-PTY / supervisor Job Object is the real teardown. taskkill /T /F
+//     is only the degraded-mode backstop (jobGuard:false — EDR/CLM blocked the job).
+//   - POSIX: there is no job-object equivalent, so process-group kill IS the primary
+//     teardown for PTYs. node-pty's Unix backend runs each PTY through forkpty→setsid,
+//     so the PTY is a session/group leader and its pid == pgid; killing the negative pid
+//     targets that whole group. Honest limitation: a grandchild that calls setsid() (some
+//     daemonized MCP servers) starts its own group and escapes -pgid; only cgroup v2
+//     delegation closes that gap (see docs/specs/process-shutdown.md).
+//
+// Never throws into the caller — teardown must not break shutdown.
+
+const childProcess = require('child_process');
+
+const IS_WIN = process.platform === 'win32';
+
+// Windows degraded-mode tree kill via taskkill. Async (spawns a child); resolves true
+// once taskkill exits 0, false otherwise. windowsHide + no shell (taskkill is a real exe).
+function _taskkillTree(pid, spawnImpl) {
+  return new Promise((resolve) => {
+    try {
+      const proc = spawnImpl('taskkill', ['/T', '/F', '/PID', String(pid)], {
+        windowsHide: true,
+        stdio: 'ignore',
+        shell: false,
+      });
+      let settled = false;
+      const done = (ok) => { if (!settled) { settled = true; resolve(ok); } };
+      proc.on('exit', (code) => done(code === 0));
+      proc.on('error', () => done(false));
+      // Bound the wait so a hung taskkill can't stall shutdown.
+      const t = setTimeout(() => done(false), 4000);
+      if (t.unref) t.unref();
+    } catch (_) {
+      resolve(false);
+    }
+  });
+}
+
+// POSIX: kill the process group led by `pid` (negative-pid), then the pid itself as a
+// fallback in case it is not actually a group leader.
+function _killGroup(pid, signal, killImpl) {
+  let any = false;
+  try { killImpl(-pid, signal); any = true; } catch (_) { /* ESRCH / EPERM */ }
+  try { killImpl(pid, signal); any = true; } catch (_) { /* may already be gone */ }
+  return any;
+}
+
+/**
+ * Best-effort tree-kill of `pid` and its descendants. Returns a Promise<boolean>.
+ * Windows uses taskkill /T /F; POSIX kills the process group.
+ * Injectable deps (`opts.spawn` / `opts.kill`) are for unit tests.
+ */
+function killProcessTree(pid, opts = {}) {
+  const signal = opts.signal || 'SIGKILL';
+  if (!pid || pid <= 0) return Promise.resolve(false);
+  if (IS_WIN) {
+    return _taskkillTree(pid, opts.spawn || childProcess.spawn);
+  }
+  return Promise.resolve(_killGroup(pid, signal, opts.kill || process.kill.bind(process)));
+}
+
+/**
+ * Synchronous best-effort tree-kill for the uncaughtException path, where the event loop
+ * is unsafe to rely on. Windows uses spawnSync(taskkill) with a short timeout; POSIX kills
+ * the process group synchronously. Returns boolean. Never throws.
+ */
+function killProcessTreeSync(pid, opts = {}) {
+  const signal = opts.signal || 'SIGKILL';
+  if (!pid || pid <= 0) return false;
+  if (IS_WIN) {
+    try {
+      const spawnSync = opts.spawnSync || childProcess.spawnSync;
+      const r = spawnSync('taskkill', ['/T', '/F', '/PID', String(pid)], {
+        windowsHide: true, stdio: 'ignore', shell: false, timeout: 3000,
+      });
+      return !!r && r.status === 0;
+    } catch (_) {
+      return false;
+    }
+  }
+  return _killGroup(pid, signal, opts.kill || process.kill.bind(process));
+}
+
+module.exports = {
+  killProcessTree,
+  killProcessTreeSync,
+  // internal, exposed for tests
+  _killGroup,
+  _taskkillTree,
+};