ai-or-die 0.1.44 → 0.1.46

package/.github/workflows/ci.yml

@@ -471,6 +471,78 @@ jobs:
             playwright-report/
           retention-days: 14
 
+  test-browser-mobile-journeys:
+    runs-on: ${{ matrix.os }}
+    needs: test
+    timeout-minutes: 12
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/ms-playwright
+            ~/AppData/Local/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - name: Install Playwright browsers
+        run: npx playwright install chromium --with-deps
+      - name: Run mobile journey tests
+        run: npx playwright test --config e2e/playwright.config.js --project mobile-journeys
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-mobile-journeys-${{ matrix.os }}
+          path: |
+            e2e/test-results/
+            playwright-report/
+          retention-days: 14
+
+  test-browser-restart:
+    runs-on: ${{ matrix.os }}
+    needs: test
+    timeout-minutes: 12
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/ms-playwright
+            ~/AppData/Local/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - name: Install Playwright browsers
+        run: npx playwright install chromium --with-deps
+      - name: Run restart tests
+        run: npx playwright test --config e2e/playwright.config.js --project restart
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-restart-${{ matrix.os }}
+          path: |
+            e2e/test-results/
+            playwright-report/
+          retention-days: 14
+
   build-binary:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 12

package/bin/supervisor.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+const { RESTART_EXIT_CODE } = require('../src/restart-manager');
+
+const RESTART_DELAY_MS = 1000;
+const CRASH_RESTART_DELAY_MS = 3000;
+const CIRCUIT_BREAKER_WINDOW_MS = 30000;
+const CIRCUIT_BREAKER_MAX_CRASHES = 3;
+const SHUTDOWN_TIMEOUT_MS = 10000;
+
+const serverScript = process.env.SUPERVISOR_CHILD_SCRIPT
+  || path.join(__dirname, 'ai-or-die.js');
+const forwardedArgs = process.argv.slice(2);
+
+let child = null;
+let shuttingDown = false;
+let crashTimestamps = [];
+let pendingRestartTimer = null;
+
+function startServer() {
+  pendingRestartTimer = null;
+  const nodeArgs = ['--expose-gc', serverScript, ...forwardedArgs];
+
+  child = spawn(process.execPath, nodeArgs, {
+    stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+    env: { ...process.env, SUPERVISED: '1' }
+  });
+
+  child.on('exit', (code, signal) => {
+    child = null;
+
+    if (shuttingDown) {
+      process.exit(0);
+      return;
+    }
+
+    if (code === 0) {
+      // Clean shutdown — don't restart
+      console.log('[supervisor] Server exited cleanly');
+      process.exit(0);
+      return;
+    }
+
+    if (code === RESTART_EXIT_CODE) {
+      // Restart requested — quick restart, don't count as crash
+      console.log(`[supervisor] Restart requested, respawning in ${RESTART_DELAY_MS}ms...`);
+      pendingRestartTimer = setTimeout(startServer, RESTART_DELAY_MS);
+      return;
+    }
+
+    // Unexpected exit — check circuit breaker
+    const now = Date.now();
+    crashTimestamps.push(now);
+    // Remove timestamps outside the window
+    crashTimestamps = crashTimestamps.filter(t => now - t < CIRCUIT_BREAKER_WINDOW_MS);
+
+    if (crashTimestamps.length >= CIRCUIT_BREAKER_MAX_CRASHES) {
+      console.error(`[supervisor] Circuit breaker: ${CIRCUIT_BREAKER_MAX_CRASHES} crashes within ${CIRCUIT_BREAKER_WINDOW_MS / 1000}s. Stopping.`);
+      process.exit(1);
+      return;
+    }
+
+    const exitInfo = signal ? `signal ${signal}` : `code ${code}`;
+    console.warn(`[supervisor] Server exited unexpectedly (${exitInfo}), restarting in ${CRASH_RESTART_DELAY_MS}ms... (crash ${crashTimestamps.length}/${CIRCUIT_BREAKER_MAX_CRASHES})`);
+    pendingRestartTimer = setTimeout(startServer, CRASH_RESTART_DELAY_MS);
+  });
+
+  child.on('error', (err) => {
+    // Spawn errors (ENOENT, EACCES) — the child process failed to launch.
+    // Port-in-use (EADDRINUSE) errors surface as child exit codes, not here.
+    console.error('[supervisor] Failed to spawn server:', err.message);
+  });
+}
+
+function shutdownGracefully() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+
+  // Cancel any pending restart timer to prevent spawning a new child during shutdown
+  if (pendingRestartTimer) {
+    clearTimeout(pendingRestartTimer);
+    pendingRestartTimer = null;
+  }
+
+  if (!child) {
+    process.exit(0);
+    return;
+  }
+
+  // Send shutdown via IPC (works on Windows, unlike SIGINT)
+  try {
+    child.send({ type: 'shutdown' });
+  } catch (_) {
+    // IPC channel may be closed
+  }
+
+  // Fallback: force kill after timeout
+  const killTimer = setTimeout(() => {
+    console.warn('[supervisor] Server did not exit within timeout, force killing');
+    // child may be null if exit handler fired between IPC send and this timer
+    if (child) {
+      try { child.kill('SIGKILL'); } catch (_) { /* ignore */ }
+    }
+    setTimeout(() => process.exit(1), 1000);
+  }, SHUTDOWN_TIMEOUT_MS);
+  killTimer.unref();
+}
+
+process.on('SIGINT', shutdownGracefully);
+// SIGTERM is not available on Windows; IPC message (below) is the Windows shutdown path
+process.on('SIGTERM', shutdownGracefully);
+// Allow test harness to trigger shutdown via IPC
+process.on('message', (msg) => {
+  if (msg && msg.type === 'shutdown') shutdownGracefully();
+});
+
+startServer();

package/e2e/playwright.config.js

@@ -127,5 +127,11 @@ module.exports = defineConfig({
       name: 'mobile-journeys',
       testMatch: '50-mobile-user-journeys.spec.js',
     },
+    // Server restart feature tests
+    {
+      name: 'restart',
+      testMatch: '20-server-restart.spec.js',
+      timeout: 120000,
+    },
   ],
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {
@@ -8,9 +8,12 @@
     "aiordie": "./bin/ai-or-die.js"
   },
   "scripts": {
-    "start": "node bin/ai-or-die.js",
-    "dev": "node bin/ai-or-die.js --dev",
+    "start": "node bin/supervisor.js",
+    "start:direct": "node bin/ai-or-die.js",
+    "dev": "node bin/supervisor.js --dev",
+    "dev:direct": "node bin/ai-or-die.js --dev",
     "test": "mocha --exit test/*.test.js",
+    "test:integration": "mocha --exit --timeout 20000 test/supervisor-integration.test.js",
     "test:browser": "npx playwright test --config e2e/playwright.config.js",
     "build:bundle": "node scripts/build-sea.js bundle",
     "build:sea": "node scripts/build-sea.js",

package/src/public/app.js

@@ -674,11 +674,16 @@ class ClaudeCodeWebInterface {
     }
 
     _setupExtraKeys() {
-        if (!this.isMobile || !window.visualViewport || typeof ExtraKeys === 'undefined') return;
+        if (!this.isMobile || typeof ExtraKeys === 'undefined') return;
 
         this.extraKeys = new ExtraKeys({ app: this });
         this._keyboardOpen = false;
 
+        // Browsers without visualViewport (Firefox Android, Samsung Internet):
+        // Initialize extra-keys but skip viewport-based keyboard detection.
+        // The extra-keys bar is still usable via manual show/hide.
+        if (!window.visualViewport) return;
+
         // Thrashing detection: if >3 resize events in 500ms, fall back to fixed threshold
         const resizeTimestamps = [];
         let useFallbackThreshold = false;
@@ -1146,6 +1151,64 @@ class ClaudeCodeWebInterface {
         }
     }
 
+    _showMemoryWarning(message) {
+        // Don't show duplicate warnings if banner already visible
+        if (document.getElementById('memoryWarningBanner')) return;
+
+        const banner = document.createElement('div');
+        banner.id = 'memoryWarningBanner';
+        banner.setAttribute('role', 'alert');
+        banner.setAttribute('aria-atomic', 'true');
+        banner.style.cssText = 'position:fixed;top:0;left:0;right:0;z-index:10000;background:#92400e;color:#fef3c7;padding:10px 16px;display:flex;align-items:center;justify-content:space-between;gap:8px;font-size:13px;font-family:Inter,sans-serif;box-shadow:0 2px 8px rgba(0,0,0,0.3);';
+
+        const text = document.createElement('span');
+        const icon = document.createElement('span');
+        icon.setAttribute('aria-hidden', 'true');
+        icon.textContent = '\u26a0\ufe0f ';
+        text.appendChild(icon);
+        if (message.supervised) {
+            text.appendChild(document.createTextNode(`Memory usage is high (${message.rss}). Save your work \u2014 you can restart now to keep things running smoothly.`));
+        } else {
+            text.appendChild(document.createTextNode(`Memory usage is high (${message.rss}). Save your work, then stop the server (Ctrl+C) and run \u201cnpm start\u201d again to free memory.`));
+        }
+        banner.appendChild(text);
+
+        const btnGroup = document.createElement('div');
+        btnGroup.style.cssText = 'display:flex;gap:8px;flex-shrink:0;';
+
+        if (message.supervised) {
+            const restartBtn = document.createElement('button');
+            restartBtn.textContent = 'Restart Now';
+            restartBtn.setAttribute('aria-label', 'Restart the server now to free memory');
+            restartBtn.style.cssText = 'background:#b91c1c;color:#fff;border:none;padding:6px 14px;border-radius:4px;cursor:pointer;font-size:12px;font-weight:600;min-height:32px;';
+            restartBtn.addEventListener('click', () => {
+                this.send({ type: 'restart_server' });
+                banner.remove();
+            });
+            btnGroup.appendChild(restartBtn);
+        }
+
+        const dismissBtn = document.createElement('button');
+        dismissBtn.textContent = 'Dismiss';
+        dismissBtn.setAttribute('aria-label', 'Dismiss memory warning');
+        dismissBtn.style.cssText = 'background:transparent;color:#fef3c7;border:1px solid #fef3c7;padding:6px 12px;border-radius:4px;cursor:pointer;font-size:12px;min-height:32px;';
+        dismissBtn.addEventListener('click', () => banner.remove());
+        btnGroup.appendChild(dismissBtn);
+
+        banner.appendChild(btnGroup);
+        document.body.appendChild(banner);
+
+        // Focus dismiss button unless user is actively typing
+        const active = document.activeElement;
+        const isTyping = active && (active.tagName === 'INPUT' || active.tagName === 'TEXTAREA' || active.isContentEditable);
+        if (!isTyping) dismissBtn.focus();
+
+        // Auto-dismiss after 90 seconds (longer to account for users stepping away)
+        setTimeout(() => {
+            if (banner.parentNode) banner.remove();
+        }, 90000);
+    }
+
     _handleVoiceMessage(message) {
         var btn = document.getElementById('voiceInputBtn');
         switch (message.type) {
@@ -1404,6 +1467,15 @@ class ClaudeCodeWebInterface {
 
                 this.socket.onopen = () => {
                     this.reconnectAttempts = 0;
+                    // Clear server restart state if we were reconnecting after a restart
+                    if (this._serverRestarting) {
+                        this._serverRestarting = false;
+                        this._restartReconnectAttempts = 0;
+                        if (this._restartTimeout) {
+                            clearTimeout(this._restartTimeout);
+                            this._restartTimeout = null;
+                        }
+                    }
                     this.updateStatus('Connected');
                     console.log('Connected to server');
                     
@@ -1438,7 +1510,14 @@ class ClaudeCodeWebInterface {
             };
             
             this.socket.onclose = (event) => {
-                if (!event.wasClean && this.reconnectAttempts < this.maxReconnectAttempts) {
+                // During server restart, don't count failures against reconnect budget
+                // but still use backoff to avoid thundering herd
+                if (this._serverRestarting) {
+                    this.updateStatus('Restarting \u2014 reconnecting\u2026');
+                    const restartBackoff = Math.min(2000 * Math.pow(1.5, this._restartReconnectAttempts || 0), 15000);
+                    this._restartReconnectAttempts = (this._restartReconnectAttempts || 0) + 1;
+                    setTimeout(() => this.reconnect(), restartBackoff);
+                } else if (!event.wasClean && this.reconnectAttempts < this.maxReconnectAttempts) {
                     this.updateStatus('Reconnecting...');
                     setTimeout(() => this.reconnect(), Math.min(this.reconnectDelay * Math.pow(2, this.reconnectAttempts), 30000));
                     this.reconnectAttempts++;
@@ -1477,6 +1556,9 @@ class ClaudeCodeWebInterface {
         if (this._reconnecting) return;
         this._reconnecting = true;
         this.disconnect();
+        // Reset overlay flag so session_joined can show start prompt if terminal
+        // exited during the disconnect (fixes stuck blank screen after reconnect)
+        this._overlayExplicitlyHidden = false;
         // Reset flow control state so stale pause signals aren't sent on new connection
         this._outputPaused = false;
         this._pendingCallbacks = 0;
@@ -1494,7 +1576,10 @@ class ClaudeCodeWebInterface {
         }
         setTimeout(() => {
             try {
-                this.connect()
+                const connectTimeout = new Promise((_, reject) =>
+                    setTimeout(() => reject(new Error('Connection timeout')), 10000)
+                );
+                Promise.race([this.connect(), connectTimeout])
                     .catch(err => console.error('Reconnection failed:', err))
                     .finally(() => { this._reconnecting = false; });
             } catch (err) {
@@ -1691,10 +1776,13 @@ class ClaudeCodeWebInterface {
                     if (isNewSession) {
                         console.log('[session_joined] New session detected, showing start prompt');
                         this.showOverlay('startPrompt');
+                    } else if (message.wasActive && message.agent) {
+                        console.log('[session_joined] Session was active before server restart, agent:', message.agent);
+                        const toolAlias = this.getAlias(message.agent) || message.agent;
+                        this.terminal.writeln(`\r\n\x1b[33mThe server was restarted and ${toolAlias} was stopped. Your session history is preserved \u2014 click \u201cStart ${toolAlias}\u201d below to pick up where you left off.\x1b[0m`);
+                        this.showOverlay('startPrompt');
                     } else {
-                        console.log('[session_joined] Existing session with stopped Claude, showing restart prompt');
-                        // For existing sessions where Claude has stopped, show start prompt
-                        // This allows the user to restart Claude in the same session
+                        console.log('[session_joined] Existing session with stopped tool, showing restart prompt');
                         this.terminal.writeln(`\r\n\x1b[33m${this.getAlias('claude')} has stopped in this session. Click "Start ${this.getAlias('claude')}" to restart.\x1b[0m`);
                         this.showOverlay('startPrompt');
                     }
@@ -1960,6 +2048,28 @@ class ClaudeCodeWebInterface {
                 this._handleVoiceMessage(message);
                 break;
 
+            // Server memory and restart events
+            case 'memory_warning':
+                this._showMemoryWarning(message);
+                break;
+
+            case 'server_restarting':
+                console.log('[server_restarting] Server restart imminent');
+                this._serverRestarting = true;
+                this._restartReconnectAttempts = 0;
+                this.reconnectAttempts = 0;
+                this.updateStatus('Restarting \u2014 please wait\u2026');
+                // Start a 60-second timeout — if server doesn't come back, show error
+                if (this._restartTimeout) clearTimeout(this._restartTimeout);
+                this._restartTimeout = setTimeout(() => {
+                    if (this._serverRestarting) {
+                        this._serverRestarting = false;
+                        this.updateStatus('Disconnected');
+                        this.showError('The server did not come back after restarting.\n\n\u2022 Refresh this page to try reconnecting\n\u2022 If the problem persists, restart the server manually with \u201cnpm start\u201d');
+                    }
+                }, 60000);
+                break;
+
             default:
                 console.log('Unknown message type:', message.type);
         }
@@ -3694,6 +3804,11 @@ class ClaudeCodeWebInterface {
             this.pendingJoinResolve = resolve;
             this.pendingJoinSessionId = sessionId;
             
+            // Reset overlay flag before joining a new session so that
+            // session_joined can correctly show/hide the overlay based on
+            // the NEW session's state, not a stale flag from the previous tab.
+            this._overlayExplicitlyHidden = false;
+
             // Send the join request
             this.send({ type: 'join_session', sessionId });
 
@@ -4012,7 +4127,7 @@ class ClaudeCodeWebInterface {
         // Container is already visible by default
         
         // Check if mobile screen
-        const isMobile = window.innerWidth <= 768;
+        const isMobile = window.innerWidth <= 820;
         const isSmallMobile = window.innerWidth <= 480;
         
         // Format tokens (K/M notation)
@@ -4152,7 +4267,7 @@ class ClaudeCodeWebInterface {
                 if (totalTokens > 0) {
                     const opusPercent = (opusTokens / totalTokens) * 100;
                     const sonnetPercent = (sonnetTokens / totalTokens) * 100;
-                    const isMobile = window.innerWidth <= 768;
+                    const isMobile = window.innerWidth <= 820;
                     
                     // Use short names on mobile, full names on desktop
                     const opusName = isMobile ? 'O' : 'Opus';
@@ -4175,7 +4290,7 @@ class ClaudeCodeWebInterface {
             }
         } else {
             // No active session or expired session - show zeros
-            const isMobile = window.innerWidth <= 768;
+            const isMobile = window.innerWidth <= 820;
             
             document.getElementById('usageTitle').textContent = '0h 0m';
             document.getElementById('usageTokens').textContent = isMobile ? '0%' : '0';

package/src/public/components/extra-keys.css

@@ -78,8 +78,8 @@
 
 @media (orientation: landscape) {
     .extra-key {
-        min-height: 36px;
-        min-width: 36px;
+        min-height: 44px;
+        min-width: 44px;
         font-size: var(--text-sm);
     }
 }

package/src/public/components/tabs.css

@@ -433,6 +433,8 @@
 .overflow-tab-close {
     width: 20px;
     height: 20px;
+    min-width: 44px;
+    min-height: 44px;
     display: flex;
     align-items: center;
     justify-content: center;

package/src/public/mobile.css

@@ -328,7 +328,7 @@
         padding: 0;
         border-width: 0;
         overflow: hidden;
-        transition: opacity 0.2s ease, height 0.2s ease;
+        transition: opacity 0.2s ease, height 0.2s ease, padding 0.2s ease, border-width 0.2s ease;
     }
     body.keyboard-open .session-tabs-bar {
         height: 0;
@@ -336,7 +336,8 @@
         overflow: hidden;
         padding: 0;
         border-width: 0;
-        transition: height 0.2s ease;
+        opacity: 0;
+        transition: opacity 0.2s ease, height 0.2s ease, padding 0.2s ease, border-width 0.2s ease;
     }
     body.keyboard-open #app {
         padding-bottom: 0 !important;

package/src/public/session-manager.js

@@ -479,7 +479,7 @@ class SessionTabManager {
     }
     
     updateTabOverflow() {
-        const isMobile = window.innerWidth <= 768;
+        const isMobile = window.innerWidth <= 820;
         const overflowWrapper = document.getElementById('tabOverflowWrapper');
         const overflowCount = document.querySelector('.tab-overflow-count');
         
@@ -647,7 +647,7 @@ class SessionTabManager {
             });
             
             // Reorder tabs based on the initial timestamps (mobile only)
-            if (window.innerWidth <= 768) {
+            if (window.innerWidth <= 820) {
                 this.reorderTabsByLastAccessed();
             }
             
@@ -808,7 +808,7 @@ class SessionTabManager {
             this.updateTabHistory(sessionId);
         }
 
-        if (window.innerWidth <= 768) {
+        if (window.innerWidth <= 820) {
             const tabIndex = this.getOrderedTabIds().indexOf(sessionId);
             if (tabIndex >= 2) this.reorderTabsByLastAccessed();
         }

package/src/restart-manager.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const RESTART_EXIT_CODE = 75;
+const MEMORY_CHECK_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+const NOTIFICATION_THROTTLE_MS = 30 * 60 * 1000; // 30 minutes
+const RESTART_BROADCAST_DELAY_MS = 500;
+const MIN_RESTART_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes between restarts
+
+/**
+ * Memory monitoring and restart trigger.
+ *
+ * This is NOT a supervisor — process lifecycle is managed by bin/supervisor.js.
+ * This module only:
+ *   1. Monitors memory and triggers GC when RSS exceeds a threshold
+ *   2. Notifies clients when memory is critically high
+ *   3. Initiates a restart by broadcasting to clients, then delegating to
+ *      the server's existing handleShutdown() with exit code 75
+ */
+class RestartManager {
+  constructor(server) {
+    this.server = server;
+    this.gcThresholdBytes = (parseInt(process.env.MEMORY_GC_THRESHOLD_MB, 10) || 1024) * 1024 * 1024;
+    this.warnThresholdBytes = (parseInt(process.env.MEMORY_WARN_THRESHOLD_MB, 10) || 2048) * 1024 * 1024;
+    this._lastWarningTime = 0;
+    this._lastRestartTime = 0;
+    this._monitorInterval = null;
+  }
+
+  startMemoryMonitoring() {
+    this._monitorInterval = setInterval(() => this._checkMemory(), MEMORY_CHECK_INTERVAL_MS);
+    // Don't block process exit
+    if (this._monitorInterval.unref) this._monitorInterval.unref();
+  }
+
+  stopMemoryMonitoring() {
+    if (this._monitorInterval) {
+      clearInterval(this._monitorInterval);
+      this._monitorInterval = null;
+    }
+  }
+
+  _checkMemory() {
+    const mem = process.memoryUsage();
+    const rssMB = (mem.rss / (1024 * 1024)).toFixed(1);
+    const heapMB = (mem.heapUsed / (1024 * 1024)).toFixed(1);
+
+    // Schedule GC via setImmediate so in-flight I/O (WebSocket frames, HTTP responses)
+    // drains first. global.gc() is synchronous and can stall the event loop 100-300ms.
+    if (mem.rss > this.gcThresholdBytes && typeof global.gc === 'function') {
+      console.log(`[memory] RSS ${rssMB} MB exceeds GC threshold, scheduling garbage collection...`);
+      setImmediate(() => this._runGc());
+    }
+
+    // Notify user when RSS exceeds warning threshold (throttled)
+    if (mem.rss > this.warnThresholdBytes) {
+      const now = Date.now();
+      if (now - this._lastWarningTime >= NOTIFICATION_THROTTLE_MS) {
+        this._lastWarningTime = now;
+        console.warn(`[memory] RSS ${rssMB} MB exceeds warning threshold (${(this.warnThresholdBytes / (1024 * 1024)).toFixed(0)} MB). Notifying clients.`);
+        this.server.broadcastToAll({
+          type: 'memory_warning',
+          rss: `${rssMB} MB`,
+          rssBytes: mem.rss,
+          heapUsed: `${heapMB} MB`,
+          heapUsedBytes: mem.heapUsed,
+          threshold: `${(this.warnThresholdBytes / (1024 * 1024)).toFixed(0)} MB`,
+          supervised: this.server.supervised
+        });
+      }
+    }
+  }
+
+  _runGc() {
+    const before = process.memoryUsage().rss;
+    // Try minor GC first (young generation, ~5ms)
+    try { global.gc({ type: 'minor' }); } catch (_) { /* ignore */ }
+
+    const afterMinor = process.memoryUsage().rss;
+    if (afterMinor > this.gcThresholdBytes) {
+      // Minor GC wasn't enough, do full GC (~100-300ms)
+      try { global.gc(); } catch (_) { /* ignore */ }
+    }
+
+    const after = process.memoryUsage().rss;
+    const reclaimedMB = ((before - after) / (1024 * 1024)).toFixed(1);
+    console.log(`[memory] GC complete. Reclaimed ${reclaimedMB} MB. RSS: ${(after / (1024 * 1024)).toFixed(1)} MB`);
+  }
+
+  async initiateRestart(reason = 'manual') {
+    // Guard: reuse the server's existing shutdown guard
+    if (this.server.isShuttingDown) {
+      console.log('[restart] Already shutting down, ignoring restart request');
+      return 'already_shutting_down';
+    }
+
+    // Rate limit: prevent restart-loop DoS
+    const now = Date.now();
+    if (now - this._lastRestartTime < MIN_RESTART_INTERVAL_MS) {
+      const waitSec = Math.ceil((MIN_RESTART_INTERVAL_MS - (now - this._lastRestartTime)) / 1000);
+      console.log(`[restart] Rate limited, ${waitSec}s remaining before next restart allowed`);
+      return 'rate_limited';
+    }
+    this._lastRestartTime = now;
+
+    console.log(`[restart] Initiating restart (reason: ${reason})`);
+
+    // Broadcast restart notification to all clients before shutdown begins.
+    // Wrapped in try/catch: a throw here (e.g., half-closed socket) must not
+    // abort the restart — the broadcast is best-effort, the shutdown is mandatory.
+    try {
+      this.server.broadcastToAll({
+        type: 'server_restarting',
+        reason
+      });
+    } catch (e) {
+      console.warn('[restart] Failed to broadcast restart notification:', e.message);
+    }
+
+    // Brief wait for WebSocket frames to be delivered
+    await new Promise(r => setTimeout(r, RESTART_BROADCAST_DELAY_MS));
+
+    // Delegate to the server's single shutdown path with restart exit code
+    await this.server.handleShutdown(RESTART_EXIT_CODE);
+    return 'restarting';
+  }
+}
+
+module.exports = RestartManager;
+module.exports.RESTART_EXIT_CODE = RESTART_EXIT_CODE;
+module.exports.MEMORY_CHECK_INTERVAL_MS = MEMORY_CHECK_INTERVAL_MS;
+module.exports.NOTIFICATION_THROTTLE_MS = NOTIFICATION_THROTTLE_MS;
+module.exports.MIN_RESTART_INTERVAL_MS = MIN_RESTART_INTERVAL_MS;

package/src/server.js

@@ -21,6 +21,7 @@ const { VSCodeTunnelManager } = require('./vscode-tunnel');
 const InstallAdvisor = require('./install-advisor');
 const SttEngine = require('./stt-engine');
 const CircularBuffer = require('./utils/circular-buffer');
+const RestartManager = require('./restart-manager');
 
 /** Foreground/background session priority constants */
 const COALESCE_MS_FG = 16;       // 60 flushes/sec for active session
@@ -77,6 +78,9 @@ class ClaudeCodeWebServer {
     this.activityBroadcastTimestamps = new Map(); // sessionId -> last broadcast timestamp
     this.startTime = Date.now(); // Track server start time
     this.isShuttingDown = false; // Flag to prevent duplicate shutdown
+    this.supervised = typeof process.send === 'function'; // Running under supervisor with IPC
+    this.restartManager = new RestartManager(this);
+    this.restartManager.startMemoryMonitoring();
     // Commands dropdown removed
     // Assistant aliases (for UI display only)
     this.aliases = {
@@ -90,6 +94,7 @@ class ClaudeCodeWebServer {
     this.setupExpress();
     this._sessionsLoaded = this.loadPersistedSessions();
     this.setupAutoSave();
+    this.setupIpcListener();
   }
   
   async loadPersistedSessions() {
@@ -126,6 +131,7 @@ class ClaudeCodeWebServer {
       for (const [id, session] of this.claudeSessions) {
         if (!session.active && session.connections.size === 0 && new Date(session.lastActivity || session.created).getTime() < sevenDaysAgo) {
           this.claudeSessions.delete(id);
+          this.activityBroadcastTimestamps.delete(id);
           this.sessionStore.markDirty();
         }
       }
@@ -143,7 +149,7 @@ class ClaudeCodeWebServer {
           ? this.sessionStore.serializeForSave(this.claudeSessions)
           : JSON.stringify([...this.claudeSessions.entries()]);
         const fs = require('fs');
-        fs.writeFileSync(this.sessionStore.sessionsFile + '.crash', data);
+        fs.writeFileSync(this.sessionStore.sessionsFile + '.crash', data, { mode: 0o600 });
       } catch (saveErr) {
         console.error('Failed to save sessions on crash:', saveErr);
       }
@@ -154,6 +160,22 @@ class ClaudeCodeWebServer {
       // Don't swallow — let it propagate to uncaughtException on Node 15+
     });
   }
+
+  setupIpcListener() {
+    if (!this.supervised) return;
+    // When running under the supervisor, listen for graceful shutdown via IPC
+    process.on('message', (msg) => {
+      if (msg && msg.type === 'shutdown') {
+        console.log('Received shutdown request via IPC');
+        this.handleShutdown();
+      }
+    });
+    // If the supervisor crashes, continue running standalone
+    process.on('disconnect', () => {
+      console.warn('IPC channel disconnected (supervisor may have crashed). Continuing standalone.');
+      this.supervised = false;
+    });
+  }
   
   setTunnelManager(tm) {
     this.tunnelManager = tm;
@@ -166,29 +188,24 @@ class ClaudeCodeWebServer {
     await this.sessionStore.saveSessions(this.claudeSessions);
   }
 
-  async handleShutdown() {
+  async handleShutdown(exitCode = 0) {
     // Prevent multiple shutdown attempts
     if (this.isShuttingDown) {
       return;
     }
     this.isShuttingDown = true;
 
-    console.log('\nGracefully shutting down...');
-    await this.saveSessionsToDisk(true);
-    if (this.autoSaveInterval) {
-      clearInterval(this.autoSaveInterval);
-    }
-    if (this.sessionEvictionInterval) {
-      clearInterval(this.sessionEvictionInterval);
-    }
-    // Stop all VS Code tunnels
-    await this.vscodeTunnel.stopAll();
-    // Clean up temp images for all sessions
-    for (const [, session] of this.claudeSessions) {
-      this.cleanupSessionImages(session);
-    }
+    // Hard timeout: if close() hangs, force exit (protects unsupervised mode)
+    const forceExitTimer = setTimeout(() => {
+      console.error(`Shutdown timed out after 15s, forcing exit (code ${exitCode})`);
+      process.exit(exitCode);
+    }, 15000);
+    forceExitTimer.unref();
+
+    console.log(`\nGracefully shutting down (exit code: ${exitCode})...`);
     await this.close();
-    process.exit(0);
+    clearTimeout(forceExitTimer);
+    process.exit(exitCode);
   }
 
   isPathWithinBase(targetPath) {
@@ -1482,6 +1499,23 @@ class ClaudeCodeWebServer {
         this.sendToWebSocket(wsInfo.ws, { type: 'pong' });
         break;
 
+      case 'restart_server':
+        if (!this.supervised) {
+          this.sendToWebSocket(wsInfo.ws, {
+            type: 'error',
+            message: 'Server is not running in supervised mode. Restart manually.'
+          });
+        } else if (this.restartManager) {
+          const result = await this.restartManager.initiateRestart('user_requested');
+          if (result === 'rate_limited') {
+            this.sendToWebSocket(wsInfo.ws, {
+              type: 'error',
+              message: 'Restart was requested too recently. Please wait a few minutes.'
+            });
+          }
+        }
+        break;
+
       case 'get_usage':
         this.handleGetUsage(wsInfo);
         break;
@@ -1649,6 +1683,8 @@ class ClaudeCodeWebServer {
       sessionName: session.name,
       workingDir: session.workingDir,
       active: session.active,
+      wasActive: session.wasActive || false,
+      agent: session.agent || null,
       outputBuffer: session.outputBuffer.slice(-200) // Send last 200 lines
     });
 
@@ -1795,6 +1831,7 @@ class ClaudeCodeWebServer {
             currentSession.agent = null;
             this.sessionStore.markDirty();
           }
+          this.activityBroadcastTimestamps.delete(sessionId);
           this.broadcastToSession(sessionId, { type: 'error', message: error.message });
           this.broadcastSessionActivity(sessionId, 'session_error');
         },
@@ -1871,6 +1908,14 @@ class ClaudeCodeWebServer {
     });
   }
 
+  broadcastToAll(data) {
+    for (const [, wsInfo] of this.webSocketConnections) {
+      if (wsInfo.ws.readyState === WebSocket.OPEN) {
+        this.sendToWebSocket(wsInfo.ws, data);
+      }
+    }
+  }
+
   // Sends a lightweight event to all WebSocket connections that are NOT joined
   // to the specified session. This enables clients to track activity in background
   // sessions for notification purposes without receiving full terminal output.
@@ -2064,7 +2109,7 @@ class ClaudeCodeWebServer {
     // Save sessions before closing
     await this.saveSessionsToDisk(true);
 
-    // Clear auto-save interval
+    // Clear all intervals
     if (this.autoSaveInterval) {
       clearInterval(this.autoSaveInterval);
     }
@@ -2075,14 +2120,32 @@ class ClaudeCodeWebServer {
       clearInterval(this.sessionEvictionInterval);
     }
 
+    // Stop memory monitoring to release the interval timer
+    if (this.restartManager) {
+      this.restartManager.stopMemoryMonitoring();
+    }
+
+    // Stop all VS Code tunnels
+    try { await this.vscodeTunnel.stopAll(); } catch (_) { /* ignore */ }
+
+    // Clean up temp images for all sessions
+    for (const [, session] of this.claudeSessions) {
+      this.cleanupSessionImages(session);
+    }
+
     if (this.wss) {
+      // Terminate existing WebSocket clients so server.close() callback fires promptly
+      // (wss.close() alone only stops new connections; open clients keep the HTTP server alive)
+      for (const client of this.wss.clients) {
+        try { client.terminate(); } catch (_) { /* ignore */ }
+      }
       this.wss.close();
     }
     if (this.server) {
       this.server.close();
     }
-    
-    // Flush pending output and stop all sessions, awaiting clean shutdown
+
+    // Flush pending output and stop all sessions with a 5-second timeout
     const stopPromises = [];
     for (const [sessionId, session] of this.claudeSessions.entries()) {
       this._flushAndClearOutputTimer(session, sessionId);
@@ -2093,7 +2156,8 @@ class ClaudeCodeWebServer {
         }
       }
     }
-    await Promise.allSettled(stopPromises);
+    const timeout = new Promise(resolve => setTimeout(resolve, 5000));
+    await Promise.race([Promise.allSettled(stopPromises), timeout]);
 
     // Clear all data
     this.claudeSessions.clear();

package/src/utils/session-store.js

@@ -3,6 +3,8 @@ const path = require('path');
 const os = require('os');
 const CircularBuffer = require('./circular-buffer');
 
+const MAX_BUFFER_BYTES_PER_SESSION = 512 * 1024; // 512KB per-session byte cap
+
 class SessionStore {
     constructor() {
         // Store sessions in user's home directory
@@ -16,6 +18,23 @@ class SessionStore {
         this._dirty = true;
     }
 
+    /**
+     * Trim an array of output lines to fit within MAX_BUFFER_BYTES_PER_SESSION.
+     * Keeps the most recent lines (end of array) and drops the oldest.
+     */
+    _capBufferByBytes(lines) {
+        let totalBytes = 0;
+        // Walk backwards from the end (newest lines) summing byte lengths
+        let startIndex = lines.length;
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const lineBytes = Buffer.byteLength(lines[i] || '', 'utf8');
+            if (totalBytes + lineBytes > MAX_BUFFER_BYTES_PER_SESSION) break;
+            totalBytes += lineBytes;
+            startIndex = i;
+        }
+        return startIndex === 0 ? lines : lines.slice(startIndex);
+    }
+
     async initializeStorage() {
         try {
             // Create storage directory if it doesn't exist
@@ -40,8 +59,10 @@ class SessionStore {
                 lastActivity: session.lastActivity || new Date(),
                 workingDir: session.workingDir || process.cwd(),
                 active: false, // Always set to false when saving (processes won't persist)
+                wasActive: session.active || false, // Preserve active state for restart awareness
+                agent: session.agent || null, // Which tool was running (claude, codex, etc.)
                 outputBuffer: (session.outputBuffer && typeof session.outputBuffer.slice === 'function')
-                    ? session.outputBuffer.slice(-100) : [], // Keep last 100 lines
+                    ? this._capBufferByBytes(session.outputBuffer.slice(-1000)) : [], // Keep last 1000 lines, capped at 512KB
                 connections: [], // Clear connections (they won't persist)
                 lastAccessed: session.lastAccessed || Date.now(),
                 // Session-specific usage tracking
@@ -64,8 +85,14 @@ class SessionStore {
             };
 
             // Write to a temporary file first, then rename (atomic operation)
+            // Use restrictive permissions (owner-only) since output may contain secrets.
+            // Note: mode 0o600 is silently ignored on Windows (which uses ACLs instead
+            // of Unix permissions). The file inherits the user's default ACL, which is
+            // acceptable but not explicitly enforced.
             const tempFile = `${this.sessionsFile}.tmp`;
-            await fs.writeFile(tempFile, JSON.stringify(data));
+            // JSON.stringify is CPU-bound; yield to pending I/O before serializing
+            const jsonStr = await new Promise(resolve => setImmediate(() => resolve(JSON.stringify(data))));
+            await fs.writeFile(tempFile, jsonStr, { mode: 0o600 });
             // Ensure directory still exists before rename (handles race conditions)
             await fs.mkdir(this.storageDir, { recursive: true });
             await fs.rename(tempFile, this.sessionsFile);
@@ -137,8 +164,8 @@ class SessionStore {
                     connections: new Set(),
                     outputBuffer: CircularBuffer.fromArray(session.outputBuffer || [], 1000),
                     maxBufferSize: 1000,
-                    // Restore usage data if available
-                    usageData: session.usageData || null
+                    // Restore usage data if available (saved under sessionUsage key)
+                    sessionUsage: session.sessionUsage || null
                 });
             }