ai-or-die 0.1.75 → 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.75",
+  "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/public/app.js

@@ -191,6 +191,18 @@ class ClaudeCodeWebInterface {
         }
         
         await this.loadConfig();
+        // Apply per-machine identity (`[HOST] ai-or-die`) to the tab/window
+        // title, mobile menu header, aria-label, and PWA meta tags now that
+        // this.hostname is populated. Must run before the first notification
+        // flash, which saves/restores the then-current document.title.
+        if (window.AppIdentity) {
+            const identity = window.AppIdentity.formatAppIdentity({ hostname: this.hostname });
+            window.AppIdentity.applyAppIdentity(identity);
+            // Surface the machine identity on the start screen too.
+            const spIdText = document.getElementById('startPromptIdentityText');
+            const spId = document.getElementById('startPromptIdentity');
+            if (spIdText && spId) { spIdText.textContent = identity; spId.hidden = false; }
+        }
         this.setupTerminal();
         this._setupExtraKeys();
         this._setupOrientationHandler();
@@ -1929,19 +1941,34 @@ class ClaudeCodeWebInterface {
             });
         }
 
-        // Section collapse/expand (keyboard accessible)
-        modal.querySelectorAll('.setting-section-header').forEach((header) => {
-            const toggle = () => {
-                const section = header.parentElement;
-                const isCollapsed = section.classList.toggle('collapsed');
-                header.setAttribute('aria-expanded', String(!isCollapsed));
-            };
-            header.addEventListener('click', toggle);
-            header.addEventListener('keydown', (e) => {
-                if (e.key === 'Enter' || e.key === ' ') {
-                    e.preventDefault();
-                    toggle();
-                }
+        // Two-pane settings nav (ARIA tablist): switch panes, roving tabindex,
+        // arrow/Home/End keyboard support. Replaces the old collapsible sections.
+        const settingsTabs = Array.from(modal.querySelectorAll('.settings-tab'));
+        const selectSettingsTab = (tab, focus = true) => {
+            settingsTabs.forEach((t) => {
+                const selected = t === tab;
+                t.setAttribute('aria-selected', String(selected));
+                t.tabIndex = selected ? 0 : -1;
+                const pane = document.getElementById(t.getAttribute('aria-controls'));
+                if (pane) pane.hidden = !selected;
+            });
+            if (focus && tab) tab.focus();
+        };
+        settingsTabs.forEach((tab) => {
+            tab.addEventListener('click', () => selectSettingsTab(tab, false));
+            tab.addEventListener('keydown', (e) => {
+                // Navigate among VISIBLE tabs only (the Install tab is hidden
+                // when running as an installed PWA) so focus never lands on an
+                // invisible element and escapes the modal focus trap.
+                const visible = settingsTabs.filter((t) => t.style.display !== 'none' && !t.hidden);
+                const idx = visible.indexOf(tab);
+                if (idx === -1) return;
+                let next = null;
+                if (e.key === 'ArrowDown' || e.key === 'ArrowRight') next = visible[(idx + 1) % visible.length];
+                else if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') next = visible[(idx - 1 + visible.length) % visible.length];
+                else if (e.key === 'Home') next = visible[0];
+                else if (e.key === 'End') next = visible[visible.length - 1];
+                if (next) { e.preventDefault(); selectSettingsTab(next); }
             });
         });
 
@@ -3917,11 +3944,15 @@ class ClaudeCodeWebInterface {
                 content.classList.remove('closing');
                 overlay.classList.remove('closing');
                 overlay.classList.remove('active');
-                overlay.style.display = 'none';
+                // Clear (don't set) the inline display so the modal hides via its
+                // base CSS rule (.<modal> { display: none }). Setting an inline
+                // display:none would win over `.active { display: flex }` and
+                // permanently block reopening the modal.
+                overlay.style.removeProperty('display');
             }, 150);
         } else {
             overlay.classList.remove('active');
-            overlay.style.display = 'none';
+            overlay.style.removeProperty('display');
         }
     }
 
@@ -4196,10 +4227,17 @@ class ClaudeCodeWebInterface {
         if (installBtn) installBtn.style.display = 'none';
         if (iosInstructions) iosInstructions.style.display = 'none';
 
-        // If running inside installed PWA, hide the entire section
-        const section = document.querySelector('[data-section="install"]');
-        if (section) {
-            section.style.display = this._isInstalled ? 'none' : '';
+        // If running inside an installed PWA, hide the Install tab + pane.
+        const installTab = document.getElementById('settingsTab-install');
+        const installPane = document.getElementById('settingsPane-install');
+        if (installTab) installTab.style.display = this._isInstalled ? 'none' : '';
+        if (installPane && this._isInstalled) installPane.hidden = true;
+        // If the Install tab was the active one and is now hidden, fall back to
+        // the first visible tab so the pane area is never left blank/unreachable.
+        if (this._isInstalled && installTab && installTab.getAttribute('aria-selected') === 'true') {
+            const firstVisible = Array.from(document.querySelectorAll('.settings-tab'))
+                .find((t) => t.style.display !== 'none');
+            if (firstVisible) firstVisible.click();
         }
 
         switch (this._installState) {