ai-or-die 0.1.76 → 0.1.78

package/bin/ai-or-die.js

@@ -43,7 +43,7 @@ program
   .option('--no-sticky-notes', 'disable per-tab AI session summaries + auto tab titles (on by default)')
   .option('--sticky-notes-model-dir <path>', 'custom directory for the sticky-note model file')
   .option('--sticky-notes-model <url>', 'override the sticky-note model GGUF download URL')
-  .option('--sticky-notes-threads <number>', 'CPU threads for sticky-note inference (default: auto, max 4)')
+  .option('--sticky-notes-threads <number>', 'CPU threads for sticky-note inference (default: auto — three-quarters of the cores on CPU, gentle on GPU)')
   .option('--no-keepalive', 'disable keeping the machine awake while the server runs (Windows only; on by default)')
   .option('--keepalive-display', 'also keep the display on (default keeps the system awake but lets the monitor sleep)');
 

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.78",
   "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) {
@@ -4243,7 +4276,24 @@ class ClaudeCodeWebServer {
           percent: progress.percent,
         });
       })
-      .then(() => this._broadcastStickyStatus())
+      .then(() => {
+        // One-time visibility into the inference backend. On CPU (no GPU — common
+        // on Windows when the Vulkan/CUDA prebuilt is incompatible) summaries are
+        // materially slower; the worker compensates with more threads + a generous
+        // watchdog timeout, but a note can still take a couple of minutes.
+        const rt = this.stickyNoteEngine.getRuntimeInfo && this.stickyNoteEngine.getRuntimeInfo();
+        if (this.dev && rt) {
+          if (rt.gpu) {
+            console.log(`[sticky-notes] engine ready (GPU backend, ${rt.threads} threads)`);
+          } else {
+            console.log(
+              `[sticky-notes] engine ready (CPU backend, ${rt.threads} threads) — ` +
+                'summaries run on CPU and may take a couple of minutes; a Vulkan/CUDA driver would accelerate them'
+            );
+          }
+        }
+        this._broadcastStickyStatus();
+      })
       .catch((err) => {
         // Allow a later AI-session start to retry after a transient failure
         // (download blip). A permanent failure (no binding) just fails fast.
@@ -5226,6 +5276,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/sticky-note-engine.js

@@ -9,21 +9,31 @@
 
 const { Worker } = require('worker_threads');
 const path = require('path');
-const os = require('os');
 const GgufModelManager = require('./utils/gguf-model-manager');
 const { isBun } = require('./utils/runtime');
 
 const MAX_QUEUE_SIZE = 3;
-const DEFAULT_INFER_TIMEOUT_MS = 60000;
+// Watchdog-grade, unconditional per-request timeout. Real grammar-constrained
+// summaries on a CPU backend (no GPU — common on Windows when the Vulkan/CUDA
+// prebuilt is incompatible) take ~90s on half-core threading and up to ~160s on
+// 2 threads. This is a true catastrophic watchdog set well above that, NOT an
+// expected boundary: correctness over speed (a slow note must still complete).
+// GPU runs finish in ~7s and return immediately, so the high cap costs them
+// nothing. The summarizer's backstop sits strictly above this (one timeout
+// owner). An explicit inferTimeoutMs still overrides.
+const DEFAULT_INFER_TIMEOUT_MS = 300000;
 const MAX_RESTART_DELAY_MS = 15000;
 const MAX_RESTART_ATTEMPTS = 5;
 
 class StickyNoteEngine {
   constructor(options = {}) {
     this._enabled = !!options.enabled;
-    // Low thread cap keeps inference gentle so the model can't saturate CPU and
-    // starve the terminal / AI agent. Summaries are infrequent + throttled.
-    this._numThreads = options.numThreads || Math.max(1, Math.min(2, os.cpus().length - 2));
+    // Thread count is auto-selected by the worker once it knows whether a GPU
+    // backend loaded (see sticky-note-threads.pickThreads), UNLESS the caller
+    // pins it explicitly (--sticky-notes-threads). Auto is signalled by leaving
+    // numThreads out of the worker data entirely.
+    this._numThreadsExplicit = Number.isFinite(Number(options.numThreads)) && Number(options.numThreads) > 0;
+    this._numThreads = this._numThreadsExplicit ? Math.floor(Number(options.numThreads)) : null;
     this._contextSize = options.contextSize || 8192;
     this._inferTimeoutMs = options.inferTimeoutMs || DEFAULT_INFER_TIMEOUT_MS;
     this._maxQueue = options.maxQueue || MAX_QUEUE_SIZE;
@@ -39,22 +49,30 @@ class StickyNoteEngine {
     this._stopping = false;
     this._initPromise = null;
     this._downloadProgress = null;
+    this._runtimeInfo = null; // { gpu, threads } reported by the worker on ready
 
     this._modelManager =
       options.modelManager ||
       new GgufModelManager({ model: options.model, modelsDir: options.modelsDir });
 
-    // Injectable for tests; default spawns the real worker thread.
+    // Injectable for tests; default spawns the real worker thread. numThreads is
+    // included ONLY when explicitly pinned — otherwise the worker auto-picks.
     this._createWorker =
       options.createWorker ||
-      (() =>
-        new Worker(path.join(__dirname, 'sticky-note-worker.js'), {
-          workerData: {
-            modelPath: this._modelManager.getModelFile(),
-            numThreads: this._numThreads,
-            contextSize: this._contextSize,
-          },
-        }));
+      (() => new Worker(path.join(__dirname, 'sticky-note-worker.js'), { workerData: this._workerData() }));
+  }
+
+  /**
+   * Build the worker's workerData. numThreads is OMITTED when auto (not pinned)
+   * so the worker auto-selects based on the GPU backend it detects; pinning it
+   * here would defeat that. Kept as a method so it is unit-testable.
+   */
+  _workerData() {
+    return {
+      modelPath: this._modelManager.getModelFile(),
+      ...(this._numThreadsExplicit ? { numThreads: this._numThreads } : {}),
+      contextSize: this._contextSize,
+    };
   }
 
   async initialize(onProgress) {
@@ -109,6 +127,11 @@ class StickyNoteEngine {
     return this._downloadProgress;
   }
 
+  /** { gpu, threads } reported by the worker on ready, or null before ready. */
+  getRuntimeInfo() {
+    return this._runtimeInfo;
+  }
+
   /**
    * Run one inference. Resolves with the model's raw output string.
    * @param {string} prompt
@@ -173,6 +196,7 @@ class StickyNoteEngine {
     this._queue = [];
     this._currentRequest = null;
     this._worker = null;
+    this._runtimeInfo = null; // dead worker — drop its reported backend/threads
 
     if (this._stopping) {
       this._status = 'unavailable';
@@ -230,6 +254,7 @@ class StickyNoteEngine {
           this._status = 'ready';
           this._restartAttempts = 0;
           this._lastSpawnError = null;
+          this._runtimeInfo = { gpu: !!msg.gpu, threads: msg.threads || null };
           worker.on('message', (m) => this._onWorkerMessage(m));
           worker.on('exit', (c) => this._onWorkerExit(c));
           this._processQueue();

package/src/sticky-note-summarizer.js

@@ -18,7 +18,7 @@ const DEFAULTS = {
   minIntervalMs: 20000, // floor between inferences for one session
   intervalFactor: 3, // adaptive: minInterval = max(floor, factor * lastDurationMs)
   turnDebounceMs: 1500, // (JSONL mode) coalesce a burst of appended turn lines
-  inferTimeoutMs: 75000, // backstop ABOVE the engine's own 60s timeout, so the
+  inferTimeoutMs: 330000, // backstop ABOVE the engine's own 300s timeout, so the
   // engine times out first (one timeout owner); this only fires if the engine
   // promise hangs entirely. Worker-side serialisation prevents concurrent runs.
   failureThreshold: 3, // consecutive failures -> open circuit breaker

package/src/sticky-note-threads.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// Thread-count policy for the sticky-note inference worker. Pure + dependency-
+// free so it can be unit-tested without spawning a worker or loading a model.
+//
+// The worker decides its own thread count AFTER getLlama() reports whether a GPU
+// backend actually loaded:
+//   - GPU present  -> the GPU carries the inference (the worker also requests full
+//     layer offload); keep a low, gentle CPU thread count so it can't saturate CPU
+//     and starve the terminal / AI agent.
+//   - No GPU (CPU) -> common on Windows when the Vulkan/CUDA prebuilt binary is
+//     incompatible. At 2 threads one grammar-constrained summary takes ~160s on a
+//     16-core box and blows every timeout; use THREE-QUARTERS of the cores (leaving
+//     a quarter for the terminal/agent) so it completes well inside the watchdog.
+// An explicit override (--sticky-notes-threads) always wins, after validation.
+// `explicit` is coerced with Number() so a numeric string (e.g. from a CLI/env
+// arg) still counts as a valid pin rather than silently falling back to auto.
+function pickThreads({ explicit, gpu, cpus } = {}) {
+  const pinned = Number(explicit);
+  if (Number.isFinite(pinned) && pinned > 0) return Math.floor(pinned);
+  const cores = Number.isFinite(cpus) && cpus > 0 ? Math.floor(cpus) : 1;
+  return gpu ? Math.max(1, Math.min(2, cores - 2)) : Math.max(1, Math.floor((cores * 3) / 4));
+}
+
+module.exports = { pickThreads };

package/src/sticky-note-worker.js

@@ -9,10 +9,10 @@
 const { parentPort, workerData } = require('worker_threads');
 const os = require('os');
 const { SYSTEM_PROMPT, NOTE_SCHEMA } = require('./sticky-note-prompt');
+const { pickThreads } = require('./sticky-note-threads');
 
 const modelPath = workerData.modelPath;
 const contextSize = workerData.contextSize || 8192;
-const numThreads = workerData.numThreads || Math.max(1, Math.min(2, os.cpus().length - 2));
 const maxTokens = workerData.maxTokens || 320;
 
 let llama;
@@ -42,12 +42,29 @@ async function init() {
   LlamaChatSessionCtor = LlamaChatSession;
 
   llama = await getLlama();
-  model = await llama.loadModel({ modelPath });
+  // availableParallelism() reflects usable parallelism better than cpus().length
+  // on Windows hybrid P/E-core machines; fall back where it's unavailable.
+  const cpus = (typeof os.availableParallelism === 'function' ? os.availableParallelism() : 0) || os.cpus().length;
+  // llama.gpu is false | 'cuda' | 'vulkan' | 'metal'; any non-empty string = GPU.
+  const gpu = !!llama.gpu;
+  const numThreads = pickThreads({ explicit: workerData.numThreads, gpu, cpus });
+  // Use the GPU fully when present: request all layers in VRAM ('max'). If the
+  // GPU can't fit them, 'max' throws — fall back to the default 'auto', which
+  // still offloads as many layers as fit (never worse than CPU-only).
+  if (gpu) {
+    try {
+      model = await llama.loadModel({ modelPath, gpuLayers: 'max' });
+    } catch {
+      model = await llama.loadModel({ modelPath });
+    }
+  } else {
+    model = await llama.loadModel({ modelPath });
+  }
   context = await model.createContext({ contextSize, threads: numThreads });
   sequence = context.getSequence();
   grammar = await llama.createGrammarForJsonSchema(NOTE_SCHEMA);
 
-  parentPort.postMessage({ type: 'ready' });
+  parentPort.postMessage({ type: 'ready', gpu, threads: numThreads });
 }
 
 async function handleInfer(msg) {

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,
+};