ai-or-die 0.1.71 → 0.1.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.71",
+  "version": "0.1.72",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {

package/src/public/app.js

@@ -1386,8 +1386,19 @@ class ClaudeCodeWebInterface {
 
         this.voiceController = new window.VoiceHandler.VoiceInputController({
             mode: this.voiceMode,
+            // Refuse a new recording while a previous transcription is still
+            // pending (single timeout slot + no correlation id — overlapping
+            // uploads would clobber each other's spinner/timeout).
+            canStart: function () {
+                return !self._voiceTranscriptionTimeout;
+            },
             onRecordingStart: function () {
                 self._playMicChime('on');
+                // Suspend the heartbeat pong-timeout while capturing: the main
+                // thread can be busy enough (esp. the ScriptProcessor fallback)
+                // to miss a pong, which would otherwise force a spurious reconnect.
+                self._voiceRecordingActive = true;
+                if (self._heartbeat) self._heartbeat.pause();
                 btn.classList.add('recording');
                 btn.classList.remove('processing');
                 btn.setAttribute('aria-pressed', 'true');
@@ -1415,6 +1426,8 @@ class ClaudeCodeWebInterface {
             },
             onRecordingStop: function (result) {
                 self._playMicChime('off');
+                self._voiceRecordingActive = false;
+                if (self._heartbeat) self._heartbeat.resume();
                 btn.classList.remove('recording');
                 btn.setAttribute('aria-pressed', 'false');
                 btn.title = 'Voice Input (Ctrl+Shift+M)';
@@ -1425,21 +1438,33 @@ class ClaudeCodeWebInterface {
                 }
 
                 if (self.voiceMode === 'local' && result && result.samples) {
+                    // Guard against a zero-sample recording (would send a
+                    // header-only frame the server rejects as "too short").
+                    if (!result.samples.byteLength || result.samples.byteLength < 2) {
+                        btn.classList.remove('processing');
+                        if (window.feedback) window.feedback.error('No audio captured');
+                        return;
+                    }
+
                     btn.classList.add('processing');
-                    // Convert Int16 PCM to base64 efficiently (chunked to avoid call stack overflow)
-                    var pcmBytes = new Uint8Array(result.samples.buffer);
-                    var CHUNK_SIZE = 8192;
-                    var parts = [];
-                    for (var i = 0; i < pcmBytes.length; i += CHUNK_SIZE) {
-                        var chunk = pcmBytes.subarray(i, Math.min(i + CHUNK_SIZE, pcmBytes.length));
-                        parts.push(String.fromCharCode.apply(null, chunk));
+
+                    // Send raw Int16 PCM as a tagged binary WS frame (no base64 —
+                    // base64's 33% inflation is what pushed long clips past the
+                    // 1 MiB frame guard and crashed the page).
+                    var frame = window.VoiceFrame.buildVoiceFrame(result.samples);
+                    var sent = self.sendBinary(frame);
+
+                    if (!sent) {
+                        // Socket not OPEN (e.g. mid-reconnect): fail fast instead of
+                        // silently dropping the frame and hanging the spinner 90 s.
+                        btn.classList.remove('processing');
+                        var notSentMsg = 'Connection not ready — recording not sent';
+                        if (window.feedback) window.feedback.error(notSentMsg);
+                        if (self.terminal) {
+                            self.terminal.write('\r\n\x1b[31m[Voice error] ' + notSentMsg + '\x1b[0m\r\n');
+                        }
+                        return;
                     }
-                    var base64Audio = btoa(parts.join(''));
-                    self.send({
-                        type: 'voice_upload',
-                        audio: base64Audio,
-                        durationMs: result.durationMs
-                    });
 
                     // Client-side timeout for transcription processing (90 seconds)
                     self._voiceTranscriptionTimeout = setTimeout(function () {
@@ -1467,6 +1492,8 @@ class ClaudeCodeWebInterface {
                 self._deliverVoiceTranscription(text);
             },
             onError: function (err) {
+                self._voiceRecordingActive = false;
+                if (self._heartbeat) self._heartbeat.resume();
                 btn.classList.remove('recording', 'processing');
                 btn.setAttribute('aria-pressed', 'false');
                 btn.title = 'Voice Input (Ctrl+Shift+M)';
@@ -1497,6 +1524,8 @@ class ClaudeCodeWebInterface {
                 }
             },
             onCancel: function () {
+                self._voiceRecordingActive = false;
+                if (self._heartbeat) self._heartbeat.resume();
                 btn.classList.remove('recording', 'processing');
                 btn.setAttribute('aria-pressed', 'false');
                 btn.title = 'Voice Input (Ctrl+Shift+M)';
@@ -2043,6 +2072,32 @@ class ClaudeCodeWebInterface {
                 if (this._heartbeat) { this._heartbeat.stop(); this._heartbeat = null; }
                 if (this._heartbeatTimer) { clearInterval(this._heartbeatTimer); this._heartbeatTimer = null; }
                 if (this._pongTimer) { clearTimeout(this._pongTimer); this._pongTimer = null; }
+
+                // A close mid-transcription must not leave the mic spinner + its
+                // 90 s timeout hanging.
+                if (this._voiceTranscriptionTimeout) {
+                    clearTimeout(this._voiceTranscriptionTimeout);
+                    this._voiceTranscriptionTimeout = null;
+                }
+                this._voiceRecordingActive = false;
+                const voiceBtn = document.getElementById('voiceInputBtn');
+                if (voiceBtn) voiceBtn.classList.remove('processing');
+
+                // Log the close code so field reports can tell a server frame
+                // rejection (1009/1003, at stop) from a heartbeat pong-timeout
+                // (4000, mid-recording).
+                console.warn('[ws] closed', event.code, event.reason || '');
+
+                // 1009/1003 are server-initiated CLEAN closes (wasClean=true): the
+                // server rejected our frame. Surface a specific message and still
+                // reconnect below, instead of dead-ending on "refresh the page".
+                const voiceClose = (window.VoiceFrame && window.VoiceFrame.classifyVoiceClose)
+                    ? window.VoiceFrame.classifyVoiceClose(event.code)
+                    : { rejected: false, message: null };
+                if (voiceClose.rejected && window.feedback) {
+                    window.feedback.error(voiceClose.message);
+                }
+
                 // During server restart, don't count failures against reconnect budget
                 // but still use backoff to avoid thundering herd
                 if (this._serverRestarting) {
@@ -2056,7 +2111,7 @@ class ClaudeCodeWebInterface {
                         if (restartGen !== this._socketGeneration) return;
                         this.reconnect();
                     }, restartBackoff);
-                } else if (!event.wasClean && this.reconnectAttempts < this.maxReconnectAttempts) {
+                } else if ((!event.wasClean || voiceClose.rejected) && this.reconnectAttempts < this.maxReconnectAttempts) {
                     this.updateStatus('Reconnecting (' + (this.reconnectAttempts + 1) + '/' + this.maxReconnectAttempts + ')...');
                     // First attempt is fast (250ms covers a server-process restart window);
                     // subsequent attempts use exponential backoff with jitter.
@@ -2174,6 +2229,17 @@ class ClaudeCodeWebInterface {
         }
     }
 
+    // Send a binary WS frame (e.g. a voice PCM frame). Returns true if it was
+    // handed to an OPEN socket, false otherwise so the caller can react to a
+    // closed/closing socket instead of silently dropping the frame.
+    sendBinary(view) {
+        if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+            this.socket.send(view);
+            return true;
+        }
+        return false;
+    }
+
     _handleStickyNoteUpdate(message) {
         if (!message || !message.sessionId) return;
         const sm = this.sessionTabManager;
@@ -4368,6 +4434,9 @@ class ClaudeCodeWebInterface {
             log: (m) => console.warn('[heartbeat]', m),
         });
         this._heartbeat.start();
+        // If a recording is in progress (e.g. this heartbeat was re-created after
+        // a reconnect mid-recording), keep pong-timeout enforcement suspended.
+        if (this._voiceRecordingActive) this._heartbeat.pause();
         // Keep _heartbeatTimer/_pongTimer references in sync for legacy code
         // (disconnect() still nulls them defensively); the watchdog owns the
         // real timer lifecycle via stop().

package/src/public/heartbeat-watchdog.js

@@ -59,6 +59,10 @@
             this._clearTimeout = t.clearTimeout || ((id) => clearTimeout(id));
             this._heartbeatTimer = null;
             this._pongTimer = null;
+            // When paused (e.g. during mic recording), pings still go out but a
+            // missed pong does NOT force a reconnect — the client main thread can
+            // be busy capturing audio and briefly stop servicing the pong.
+            this._paused = false;
         }
 
         _isStale() {
@@ -75,6 +79,9 @@
             } catch (_) {
                 return;
             }
+            // Paused: keep liveness pings flowing but do NOT arm the pong-timeout
+            // (a missed pong while recording must not force-close the socket).
+            if (this._paused) return;
             if (this._pongTimer) this._clearTimeout(this._pongTimer);
             this._pongTimer = this._setTimeout(() => {
                 if (this._isStale()) return;
@@ -118,6 +125,24 @@
                 this._pongTimer = null;
             }
         }
+
+        /**
+         * Suspend pong-timeout enforcement (pings continue). Use while the client
+         * main thread may be busy enough to miss a pong — e.g. mic recording —
+         * so a transient stall doesn't trigger a spurious reconnect.
+         */
+        pause() {
+            this._paused = true;
+            if (this._pongTimer) {
+                this._clearTimeout(this._pongTimer);
+                this._pongTimer = null;
+            }
+        }
+
+        /** Resume normal pong-timeout enforcement (next ping re-arms it). */
+        resume() {
+            this._paused = false;
+        }
     }
 
     return HeartbeatWatchdog;

package/src/public/index.html

@@ -801,6 +801,7 @@
     <script src="vscode-tunnel.js"></script>
     <script src="app-tunnel.js"></script>
     <script src="voice-handler.js"></script>
+    <script src="voice-frame.js"></script>
     <script src="command-palette.js"></script>
     <script src="extra-keys.js"></script>
     <script src="input-overlay.js"></script>

package/src/public/voice-frame.js

@@ -0,0 +1,73 @@
+/**
+ * VoiceFrame
+ *
+ * Pure helpers for the client->server binary voice path, factored out of app.js
+ * so they can be unit-tested in Node. Mirrors the UMD shape of
+ * heartbeat-watchdog.js (CommonJS in tests, `window.VoiceFrame` in the browser).
+ */
+(function (global, factory) {
+    if (typeof module === 'object' && module.exports) {
+        module.exports = factory();
+    } else {
+        global.VoiceFrame = factory();
+    }
+}(typeof self !== 'undefined' ? self : this, function () {
+
+    // Wire header: [ "VUP1" (4) ][ version (1) ][ type (1) ] then raw 16-bit PCM.
+    var MAGIC_V = 0x56; // 'V'
+    var MAGIC_U = 0x55; // 'U'
+    var MAGIC_P = 0x50; // 'P'
+    var MAGIC_1 = 0x31; // '1'
+    var PROTO_VERSION = 0x01;
+    var FRAME_TYPE_PCM = 0x01;
+    var HEADER_BYTES = 6;
+
+    /**
+     * Build a binary voice frame: the 6-byte header followed by the PCM bytes of
+     * `samples`. Uses byteOffset/byteLength so a subarray-backed Int16Array is
+     * copied correctly (not the whole underlying buffer).
+     *
+     * @param {Int16Array} samples
+     * @returns {Uint8Array}
+     */
+    function buildVoiceFrame(samples) {
+        var pcm = new Uint8Array(samples.buffer, samples.byteOffset, samples.byteLength);
+        var frame = new Uint8Array(HEADER_BYTES + pcm.length);
+        frame[0] = MAGIC_V;
+        frame[1] = MAGIC_U;
+        frame[2] = MAGIC_P;
+        frame[3] = MAGIC_1;
+        frame[4] = PROTO_VERSION;
+        frame[5] = FRAME_TYPE_PCM;
+        frame.set(pcm, HEADER_BYTES);
+        return frame;
+    }
+
+    /**
+     * Classify a WebSocket close code for the voice path.
+     *
+     * 1009 (server rejected an oversized frame) and 1003 (unsupported/garbage
+     * binary) are server-initiated CLEAN closes, so `event.wasClean` is true and
+     * the default onclose path would SKIP reconnect and dead-end on
+     * "refresh the page". Treat them as recoverable: show a specific message and
+     * still reconnect (bounded by the normal attempt budget).
+     *
+     * @param {number} code
+     * @returns {{rejected: boolean, message: (string|null)}}
+     */
+    function classifyVoiceClose(code) {
+        if (code === 1009 || code === 1003) {
+            return {
+                rejected: true,
+                message: 'A voice message was rejected by the server. Reconnecting…'
+            };
+        }
+        return { rejected: false, message: null };
+    }
+
+    return {
+        HEADER_BYTES: HEADER_BYTES,
+        buildVoiceFrame: buildVoiceFrame,
+        classifyVoiceClose: classifyVoiceClose
+    };
+}));

package/src/public/voice-handler.js

@@ -625,6 +625,9 @@ function VoiceInputController(options) {
   this._onTranscription = options.onTranscription || null;
   this._onError = options.onError || null;
   this._onCancel = options.onCancel || null;
+  // Optional predicate: if it returns false, a start request is ignored (e.g.
+  // a previous transcription is still pending). Gates both button + keyboard.
+  this._canStart = options.canStart || null;
 
   this._recorder = null;
   this._starting = false;
@@ -670,6 +673,7 @@ VoiceInputController.prototype.startRecording = function () {
   var self = this;
   if (self._starting) return;
   if (self._recorder && self._recorder.isRecording) return;
+  if (self._canStart && !self._canStart()) return;
 
   self._starting = true;
   self._recorder = self._createRecorder();

package/src/server.js

@@ -1,6 +1,7 @@
 const express = require('express');
 const http = require('http');
 const https = require('https');
+const net = require('net');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -46,6 +47,18 @@ const RestartManager = require('./restart-manager');
 // See docs/audits/hot-03-ws-frame-size.md.
 const MAX_WS_MESSAGE_BYTES = 1 * 1024 * 1024;
 
+// Inbound binary voice frames (client mic -> server STT) bypass the JSON guard
+// above. Framing + validation (incl. the Buffer[] fragmented-frame normalize)
+// lives in utils/ws-voice-frame so it can be unit-tested without a live socket.
+// A frame is bounded by MAX_VOICE_BINARY_FRAME_BYTES (oversize -> 1009 close,
+// like the text guard); a bad/short header -> 1003 close.
+const {
+  MAX_VOICE_PCM_BYTES,
+  MAX_VOICE_BINARY_FRAME_BYTES,
+  normalizeBinaryMessage,
+  classifyVoiceFrame,
+} = require('./utils/ws-voice-frame');
+
 // Pre-built PWA screenshot SVG buffers (served at /screenshot-wide.png and /screenshot-narrow.png)
 const SCREENSHOT_WIDE_BUF = Buffer.from(`
   <svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg">
@@ -148,8 +161,6 @@ class ClaudeCodeWebServer {
       modelsDir: options.sttModelDir,
       numThreads: options.sttThreads ? parseInt(options.sttThreads, 10) : undefined,
     });
-    this._voiceUploadCounts = new Map();
-
     // Per-tab local-LLM "sticky note" summariser. ON by default for AI-agent
     // tabs; disable globally with --no-sticky-notes / AIORDIE_DISABLE_STICKY_NOTES=1
     // (sticky-notes only — does NOT affect STT). The engine lazily downloads its
@@ -1319,11 +1330,6 @@ class ClaudeCodeWebServer {
       // weeks of uptime. See _cleanupFsWatchSession.
       this._cleanupFsWatchSession(sessionId, 'session_deleted');
 
-      // Drop the voice-upload rate-limit history for this session. Map
-      // grew unbounded across session-create/delete churn on long-lived
-      // servers (smaller cousin of the _fsWatchSessions leak).
-      this._voiceUploadCounts.delete(sessionId);
-
       // Stop + tear down the summariser so an in-flight inference is discarded.
       this.stickyNoteSummarizer.cancel(sessionId);
       this._stickyJsonl.delete(sessionId);
@@ -3151,6 +3157,7 @@ class ClaudeCodeWebServer {
     this._ensureStickyNoteEngine();
 
     let server;
+    let wsHost; // the server the WebSocket server attaches to (TLS server in HTTPS mode)
 
     if (this.useHttps) {
       let cert, key;
@@ -3177,13 +3184,90 @@ class ClaudeCodeWebServer {
         console.log('        Browsers will show a security warning on first visit.');
         console.log('        For a trusted, installable origin use \x1b[1m--tunnel\x1b[0m.');
       }
-      server = https.createServer({ cert, key }, this.app);
+
+      // The real TLS app server. The WebSocket server attaches HERE so a wss://
+      // upgrade arrives over an encrypted TLSSocket (req.socket.encrypted stays
+      // true for the secure-context / voice checks).
+      const tlsServer = https.createServer({ cert, key }, this.app);
+
+      // Build the https redirect target from the SAME host:port the client
+      // reached. The Host header is client-controlled, so accept ONLY a bare
+      // hostname[:port] (or [ipv6][:port]) — reject userinfo (`@`), paths, and
+      // control chars to prevent an open redirect to an external origin
+      // (e.g. Host: user:pass@evil.com). Fall back to localhost otherwise.
+      const redirectLocation = (req) => {
+        const raw = String(req.headers.host || '');
+        const validHost = /^[A-Za-z0-9.-]+(?::\d+)?$/.test(raw)
+          || /^\[[0-9a-fA-F:]+\](?::\d+)?$/.test(raw);
+        const hostname = validHost ? raw.replace(/:\d+$/, '') : 'localhost';
+        const port = req.socket.localPort || this.port;
+        // req.url is parser-validated (no CR/LF in a valid request target).
+        return `https://${hostname}:${port}${req.url}`.replace(/[\r\n]/g, '');
+      };
+
+      // Plaintext HTTP on the SAME port -> redirect to https. A user who reaches
+      // http://host:PORT is auto-upgraded instead of getting an opaque
+      // TLS-handshake error. 307 keeps the method and is not cached as permanent
+      // (switching the port back to http mode later isn't poisoned by a stale 301).
+      const httpRedirectServer = http.createServer((req, res) => {
+        const location = redirectLocation(req);
+        res.writeHead(307, { Location: location, 'Content-Type': 'text/plain' });
+        res.end(`Redirecting to ${location}\n`);
+      });
+      // A plaintext ws:// upgrade to the TLS port: answer with the same redirect
+      // (written raw — an upgrade has no res object) instead of an abrupt RST.
+      httpRedirectServer.on('upgrade', (req, socket) => {
+        const location = redirectLocation(req);
+        try {
+          socket.end(
+            'HTTP/1.1 307 Temporary Redirect\r\n' +
+            `Location: ${location}\r\n` +
+            'Connection: close\r\n\r\n'
+          );
+        } catch (_) { try { socket.destroy(); } catch (__) { /* ignore */ } }
+      });
+
+      // Front both with a 1-byte sniffer: a TLS ClientHello starts with 0x16
+      // (handshake record); anything else is plaintext HTTP. One listening port
+      // therefore serves both — http:// and https:// to PORT both work.
+      this._proxySockets = new Set();
+      server = net.createServer((socket) => {
+        this._proxySockets.add(socket);
+        socket.once('close', () => this._proxySockets.delete(socket));
+        // Pre-handoff guards: drop a connection that errors or sends no data
+        // (port scanner / slowloris) before we know which server owns it. Both
+        // are cleared the moment we route, so the target server's own lifecycle
+        // and timeouts take over cleanly.
+        const sniffTimer = setTimeout(() => { try { socket.destroy(); } catch (_) { /* ignore */ } }, 10000);
+        const onSniffError = () => {
+          clearTimeout(sniffTimer);
+          try { socket.destroy(); } catch (_) { /* ignore */ }
+        };
+        socket.on('error', onSniffError);
+        socket.once('readable', () => {
+          clearTimeout(sniffTimer);
+          socket.removeListener('error', onSniffError);
+          const chunk = socket.read(1);
+          if (!chunk) { socket.destroy(); return; }
+          socket.unshift(chunk);
+          const target = chunk[0] === 0x16 ? tlsServer : httpRedirectServer;
+          target.emit('connection', socket);
+        });
+      });
+
+      this._tlsServer = tlsServer;
+      this._httpRedirectServer = httpRedirectServer;
+      wsHost = tlsServer;
+      console.log('        http:// requests on this port auto-upgrade to https.');
     } else {
       server = http.createServer(this.app);
+      this._tlsServer = null;
+      this._httpRedirectServer = null;
+      wsHost = server;
     }
 
     this.wss = new WebSocket.Server({
-      server,
+      server: wsHost,
       maxPayload: 8 * 1024 * 1024,
       // Compression disabled — binary frames already send with compress:false,
       // and JSON control messages are small/infrequent. Saves ~300KB per connection
@@ -3237,7 +3321,39 @@ class ClaudeCodeWebServer {
     };
     this.webSocketConnections.set(wsId, wsInfo);
 
-    ws.on('message', (message) => {
+    ws.on('message', (message, isBinary) => {
+      // Inbound BINARY frames are voice audio (client mic). Handle them BEFORE
+      // the JSON guard below: they legitimately exceed 1 MiB (up to 3.84 MB of
+      // 120 s PCM) and must not be killed by the text-frame guard. They are
+      // still bounded (oversize -> 1009; bad/short header -> 1003) so this does
+      // not reopen the event-loop-DoS hole the JSON guard closes.
+      if (isBinary) {
+        // ws delivers a Buffer when un-fragmented and a Buffer[] when the frame
+        // arrived in multiple WS continuation fragments. Normalize first, then
+        // classify on the normalized buffer (never on `message.length`, which is
+        // the fragment COUNT for an array).
+        const buf = normalizeBinaryMessage(message);
+        const verdict = classifyVoiceFrame(buf);
+        if (verdict.action === 'oversize') {
+          try {
+            this.sendToWebSocket(ws, {
+              type: 'error',
+              code: 'message_too_large',
+              message: `Binary voice frame exceeds ${MAX_VOICE_BINARY_FRAME_BYTES} bytes`,
+              received_bytes: buf.length,
+              limit_bytes: MAX_VOICE_BINARY_FRAME_BYTES,
+            });
+          } catch (_) { /* socket may be half-closed */ }
+          try { ws.close(1009, 'message_too_large'); } catch (_) {}
+          return;
+        }
+        if (verdict.action === 'unsupported') {
+          try { ws.close(1003, 'unsupported binary'); } catch (_) {}
+          return;
+        }
+        this.handleVoiceBinary(wsId, verdict.pcm);
+        return;
+      }
       // HOT-08: application-layer size guard, runs BEFORE JSON.parse.
       // Buffer.byteLength handles both string and Buffer message types.
       // On oversize, send a marker error frame and close with WS-standard
@@ -4677,11 +4793,11 @@ class ClaudeCodeWebServer {
         }
 
         // Same per-session cleanup contract as the DELETE handler:
-        // tear down any orphan fs-watch SSE + voice-upload history
-        // BEFORE removing the parent session entry, otherwise the
-        // chokidar watcher leaks (PR #99 regression).
+        // tear down any orphan fs-watch SSE BEFORE removing the parent session
+        // entry, otherwise the chokidar watcher leaks (PR #99 regression). The
+        // voice-upload rate-limit history lives on the session object and is
+        // dropped with it below.
         try { this._cleanupFsWatchSession(top.id, 'session_evicted'); } catch (_) { /* ignore */ }
-        try { this._voiceUploadCounts.delete(top.id); } catch (_) { /* ignore */ }
         try { this.stickyNoteSummarizer.cancel(top.id); } catch (_) { /* ignore */ }
         try { this._stickyJsonl.delete(top.id); } catch (_) { /* ignore */ }
         if (this._foregroundSessionId === top.id) this._foregroundSessionId = null;
@@ -4888,7 +5004,8 @@ class ClaudeCodeWebServer {
         total: this.claudeSessions.size,
         ws_connections: this.webSocketConnections.size,
         fs_watch_sessions: (this._fsWatchSessions && this._fsWatchSessions.size) || 0,
-        voice_upload_counts: (this._voiceUploadCounts && this._voiceUploadCounts.size) || 0,
+        voice_upload_counts: Array.from(this.claudeSessions.values())
+          .filter(s => s._voiceUploadTimestamps && s._voiceUploadTimestamps.length).length,
         activity_broadcast_timestamps: (this.activityBroadcastTimestamps && this.activityBroadcastTimestamps.size) || 0,
       },
       // DISK-02/03: cached disk usage sample (60 s TTL, never blocks the
@@ -5225,6 +5342,23 @@ class ClaudeCodeWebServer {
     if (this.server) {
       this.server.close();
     }
+    // In HTTPS mode `this.server` is the TLS-sniffing proxy that owns the
+    // listening port; the TLS app server and the http->https redirect server sit
+    // behind it. Sockets are handed to them via emit('connection'), bypassing
+    // their internal connection tracking, so destroy the proxied sockets here
+    // (and close the inner servers) to avoid keep-alive connections lingering.
+    if (this._proxySockets) {
+      for (const s of this._proxySockets) {
+        try { s.destroy(); } catch (_) { /* ignore */ }
+      }
+      this._proxySockets.clear();
+    }
+    if (this._tlsServer) {
+      try { this._tlsServer.close(); } catch (_) { /* ignore */ }
+    }
+    if (this._httpRedirectServer) {
+      try { this._httpRedirectServer.close(); } catch (_) { /* ignore */ }
+    }
 
     // Flush pending output and stop all sessions with a 5-second timeout
     const stopPromises = [];
@@ -5456,10 +5590,40 @@ class ClaudeCodeWebServer {
     }
   }
 
+  // Thin shim for the legacy base64-JSON voice_upload path. The 'Missing audio
+  // data' guard must live HERE (the binary path has no data.audio); after the
+  // binary-frame switch no live client emits this, but it is kept for
+  // back-compat and shares the validation/transcribe core below.
   async handleVoiceUpload(wsId, data) {
     const wsInfo = this.webSocketConnections.get(wsId);
     if (!wsInfo) return;
 
+    if (!data.audio || typeof data.audio !== 'string') {
+      this.sendToWebSocket(wsInfo.ws, {
+        type: 'voice_transcription_error',
+        message: 'Missing audio data'
+      });
+      return;
+    }
+
+    await this._processVoicePcm(wsId, Buffer.from(data.audio, 'base64'));
+  }
+
+  // Binary voice frame path. The ws dispatcher has already validated the 6-byte
+  // header and sliced it off, so `pcmBuffer` is raw 16-bit PCM.
+  async handleVoiceBinary(wsId, pcmBuffer) {
+    await this._processVoicePcm(wsId, pcmBuffer);
+  }
+
+  // Shared voice core for both the base64 shim and the binary path. Check order
+  // is cheapest/most-restrictive first; the rate limit stays BEFORE the isReady
+  // gate (so it is enforced even when STT is unavailable), and the int16->float32
+  // conversion is deferred to the STT worker (transcribePcm16) rather than run on
+  // the event loop here.
+  async _processVoicePcm(wsId, pcmBuffer) {
+    const wsInfo = this.webSocketConnections.get(wsId);
+    if (!wsInfo) return;
+
     // Reject voice uploads over HTTP from non-localhost origins (defense-in-depth)
     if (!wsInfo.secure && !this._isLocalhostConnection(wsInfo.ws)) {
       this.sendToWebSocket(wsInfo.ws, {
@@ -5494,23 +5658,21 @@ class ClaudeCodeWebServer {
       return;
     }
 
-    // Rate limit: max 10 voice uploads per minute per session (check early to prevent abuse)
-    const sessionId = wsInfo.claudeSessionId;
-    if (!this._voiceUploadCounts.has(sessionId)) {
-      this._voiceUploadCounts.set(sessionId, []);
-    }
-    const timestamps = this._voiceUploadCounts.get(sessionId);
+    // Rate limit: max 10 voice uploads per minute per session. State lives on the
+    // session object (mirrors image uploads at saveImageToTemp) so it shares the
+    // session's lifetime — GC'd on session delete/evict, and correctly survives a
+    // WS reconnect (the budget must NOT reset when the socket drops).
     const now = Date.now();
-    const recent = timestamps.filter(ts => now - ts < 60000);
-    this._voiceUploadCounts.set(sessionId, recent);
-    if (recent.length >= 10) {
+    if (!session._voiceUploadTimestamps) session._voiceUploadTimestamps = [];
+    session._voiceUploadTimestamps = session._voiceUploadTimestamps.filter(ts => now - ts < 60000);
+    if (session._voiceUploadTimestamps.length >= 10) {
       this.sendToWebSocket(wsInfo.ws, {
         type: 'voice_transcription_error',
         message: 'Rate limit exceeded: maximum 10 voice uploads per minute.'
       });
       return;
     }
-    recent.push(now);
+    session._voiceUploadTimestamps.push(now);
 
     if (!this.sttEngine.isReady()) {
       this.sendToWebSocket(wsInfo.ws, {
@@ -5521,19 +5683,8 @@ class ClaudeCodeWebServer {
     }
 
     try {
-      // Validate audio data
-      if (!data.audio || typeof data.audio !== 'string') {
-        this.sendToWebSocket(wsInfo.ws, {
-          type: 'voice_transcription_error',
-          message: 'Missing audio data'
-        });
-        return;
-      }
-
-      const audioBuffer = Buffer.from(data.audio, 'base64');
-
       // Max 120s of 16kHz 16-bit mono PCM = 3,840,000 bytes
-      if (audioBuffer.length > 3840000) {
+      if (pcmBuffer.length > MAX_VOICE_PCM_BYTES) {
         this.sendToWebSocket(wsInfo.ws, {
           type: 'voice_transcription_error',
           message: 'Audio too long (max 120 seconds)'
@@ -5541,7 +5692,7 @@ class ClaudeCodeWebServer {
         return;
       }
 
-      if (audioBuffer.length < 2) {
+      if (pcmBuffer.length < 2) {
         this.sendToWebSocket(wsInfo.ws, {
           type: 'voice_transcription_error',
           message: 'Audio too short'
@@ -5549,7 +5700,7 @@ class ClaudeCodeWebServer {
         return;
       }
 
-      if (audioBuffer.length % 2 !== 0) {
+      if (pcmBuffer.length % 2 !== 0) {
         this.sendToWebSocket(wsInfo.ws, {
           type: 'voice_transcription_error',
           message: 'Invalid audio data: buffer length must be even (16-bit PCM samples)'
@@ -5557,11 +5708,8 @@ class ClaudeCodeWebServer {
         return;
       }
 
-
-      // Convert Int16 PCM buffer to Float32Array for sherpa-onnx
-      const float32 = this._int16ToFloat32(audioBuffer);
-
-      const text = await this.sttEngine.transcribe(float32);
+      // Raw int16 PCM -> the worker converts to Float32 off the event loop.
+      const text = await this.sttEngine.transcribePcm16(pcmBuffer);
 
       this.sendToWebSocket(wsInfo.ws, {
         type: 'voice_transcription',
@@ -5652,17 +5800,6 @@ class ClaudeCodeWebServer {
     }
   }
 
-  _int16ToFloat32(int16Buffer) {
-    // Copy to ensure 2-byte alignment (Node.js Buffers may have odd byteOffset)
-    const aligned = new Uint8Array(int16Buffer).buffer;
-    const int16 = new Int16Array(aligned);
-    const float32 = new Float32Array(int16.length);
-    for (let i = 0; i < int16.length; i++) {
-      float32[i] = int16[i] / 32768.0;
-    }
-    return float32;
-  }
-
   async saveImageToTemp(session, data) {
     // Primary temp dir: .claude-images inside the session working directory
     let tempDir = path.join(session.workingDir, '.claude-images');

package/src/stt-engine.js

@@ -93,6 +93,71 @@ class SttEngine {
     return promise;
   }
 
+  /**
+   * Transcribe raw 16-bit PCM. The int16->float32 conversion is deferred to the
+   * worker thread (see stt-worker.js) so the server event loop never runs the
+   * per-sample loop. Accepts an Int16Array, an ArrayBuffer, or any ArrayBuffer
+   * view (e.g. a Node Buffer) of raw little-endian 16-bit samples.
+   *
+   * @param {Int16Array|ArrayBuffer|ArrayBufferView} int16
+   * @returns {Promise<string>}
+   */
+  transcribePcm16(int16) {
+    const int16arr = this._toInt16Array(int16);
+
+    if (this._sttEndpoint) {
+      // External endpoint has no worker — convert here and reuse the float32 path.
+      const float32 = new Float32Array(int16arr.length);
+      for (let i = 0; i < int16arr.length; i++) {
+        float32[i] = int16arr[i] / 32768.0;
+      }
+      return this._transcribeExternal(float32);
+    }
+
+    if (this._status !== 'ready') {
+      throw new Error(`STT engine not ready (status: ${this._status})`);
+    }
+
+    if (this._queue.length >= MAX_QUEUE_SIZE) {
+      throw new Error('STT busy, try again later');
+    }
+
+    const id = ++this._requestIdCounter;
+
+    const promise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._removeFromQueue(id);
+        reject(new Error('Transcription timed out'));
+      }, TRANSCRIPTION_TIMEOUT_MS);
+
+      this._queue.push({ id, pcm16: int16arr, resolve, reject, timer });
+    });
+
+    this._processQueue();
+    return promise;
+  }
+
+  // Copy an int16 input into a fresh, offset-0, even-length Int16Array. Always
+  // copies (even an Int16Array input) so the queued buffer is solely owned and
+  // can be safely TRANSFERRED to the worker. A Node Buffer slice can have an odd
+  // byteOffset (a direct `new Int16Array(buf.buffer, off)` would throw); an odd
+  // byteLength is floored to whole 16-bit samples — callers already reject odd
+  // lengths, this is defense-in-depth so the method never throws RangeError.
+  _toInt16Array(int16) {
+    let bytes;
+    if (int16 instanceof Int16Array || ArrayBuffer.isView(int16)) {
+      bytes = new Uint8Array(int16.buffer, int16.byteOffset, int16.byteLength);
+    } else if (int16 instanceof ArrayBuffer) {
+      bytes = new Uint8Array(int16);
+    } else {
+      throw new Error('transcribePcm16 expects an Int16Array, ArrayBuffer, or typed-array view');
+    }
+    const evenLen = bytes.byteLength - (bytes.byteLength % 2);
+    const copy = new Uint8Array(evenLen);
+    copy.set(bytes.subarray(0, evenLen));
+    return new Int16Array(copy.buffer);
+  }
+
   _processQueue() {
     if (this._currentRequest || this._queue.length === 0 || !this._worker) {
       return;
@@ -101,11 +166,23 @@ class SttEngine {
     const request = this._queue[0];
     this._currentRequest = request;
 
-    this._worker.postMessage({
-      type: 'transcribe',
-      id: request.id,
-      samples: request.samples
-    });
+    // pcm16 path: TRANSFER the (solely-owned, freshly-copied by _toInt16Array)
+    // buffer to the worker — avoids a multi-MB structured-clone copy on the event
+    // loop. Safe because each request is posted exactly once (on worker crash the
+    // queue is rejected + cleared, so a posted/detached buffer is never requeued).
+    if (request.pcm16 !== undefined) {
+      this._worker.postMessage({
+        type: 'transcribe',
+        id: request.id,
+        pcm16: request.pcm16
+      }, [request.pcm16.buffer]);
+    } else {
+      this._worker.postMessage({
+        type: 'transcribe',
+        id: request.id,
+        samples: request.samples
+      });
+    }
   }
 
   _onWorkerMessage(msg) {

package/src/stt-worker.js

@@ -3,6 +3,7 @@
 const { parentPort, workerData } = require('worker_threads');
 const path = require('path');
 const os = require('os');
+const { pcm16ToFloat32 } = require('./utils/pcm.js');
 
 // Set platform-specific library paths BEFORE requiring sherpa-onnx-node.
 // The native .node addon dynamically loads shared libraries (onnxruntime.dll,
@@ -74,10 +75,22 @@ try {
 parentPort.on('message', (msg) => {
   if (msg.type === 'transcribe') {
     try {
-      // msg.samples is a Float32Array (transferred or copied from main thread)
-      const samples = msg.samples instanceof Float32Array
-        ? msg.samples
-        : new Float32Array(msg.samples);
+      // Two input shapes:
+      //  - msg.pcm16: raw 16-bit PCM (Int16Array). Conversion to Float32 runs
+      //    HERE, in the worker thread, so the server event loop never does the
+      //    per-sample loop (HOL-blocking input/ping for long clips).
+      //  - msg.samples: a Float32Array (legacy / external-endpoint callers).
+      let samples;
+      if (msg.pcm16 !== undefined && msg.pcm16 !== null) {
+        const int16 = msg.pcm16 instanceof Int16Array
+          ? msg.pcm16
+          : new Int16Array(msg.pcm16);
+        samples = pcm16ToFloat32(int16);
+      } else {
+        samples = msg.samples instanceof Float32Array
+          ? msg.samples
+          : new Float32Array(msg.samples);
+      }
 
       const stream = recognizer.createStream();
       stream.acceptWaveform({ samples, sampleRate: 16000 });

package/src/utils/pcm.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * Convert 16-bit PCM samples to normalized Float32 [-1, 1).
+ *
+ * Divisor is 32768.0 for every sample (matching the original server-side
+ * conversion): positive full-scale 32767 maps to ~0.99997, negative full-scale
+ * -32768 maps to exactly -1.0. Used by the STT worker (off the server event
+ * loop) and exercised directly in unit tests.
+ *
+ * @param {Int16Array} int16
+ * @returns {Float32Array}
+ */
+function pcm16ToFloat32(int16) {
+  const out = new Float32Array(int16.length);
+  for (let i = 0; i < int16.length; i++) {
+    out[i] = int16[i] / 32768.0;
+  }
+  return out;
+}
+
+module.exports = { pcm16ToFloat32 };

package/src/utils/ws-voice-frame.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * Inbound binary voice-frame framing (client mic -> server STT).
+ *
+ * Wire format:
+ *   [4 bytes ASCII "VUP1"][1 byte version][1 byte type][raw 16-bit PCM @16kHz mono]
+ *
+ * Pure (no I/O) so the dispatcher logic in server.js can be unit-tested without
+ * a live socket — in particular the Buffer[] (fragmented frame) normalization,
+ * which is the one genuinely platform-dependent receive path.
+ */
+
+const VOICE_MAGIC = Buffer.from('VUP1', 'ascii');
+const VOICE_PROTO_VERSION = 1;
+const VOICE_FRAME_TYPE_PCM = 0x01;
+const VOICE_HEADER_BYTES = 6; // magic(4) + version(1) + type(1)
+const MAX_VOICE_PCM_BYTES = 3840000; // 120 s @ 16 kHz / 16-bit / mono
+const MAX_VOICE_BINARY_FRAME_BYTES = VOICE_HEADER_BYTES + MAX_VOICE_PCM_BYTES;
+
+/**
+ * Normalize ws RawData to a single Buffer. ws delivers a Buffer when the frame
+ * is un-fragmented, a Buffer[] when it arrived in multiple WS continuation
+ * fragments (1-4 MB voice frames fragment variably across browsers/proxies/
+ * tunnels), or an ArrayBuffer under non-default options. Always size-check the
+ * RESULT of this, never the raw message (whose `.length` is the fragment count
+ * for an array).
+ *
+ * The concatenation is bounded: the ws server's `maxPayload` (8 MiB) caps the
+ * total message length during fragment reassembly and closes 1009 before the
+ * 'message' event fires, so this never concatenates more than 8 MiB.
+ *
+ * @param {Buffer|Buffer[]|ArrayBuffer|ArrayBufferView} message
+ * @returns {Buffer}
+ */
+function normalizeBinaryMessage(message) {
+  if (Buffer.isBuffer(message)) return message;
+  if (Array.isArray(message)) return Buffer.concat(message);
+  return Buffer.from(message);
+}
+
+/**
+ * Classify a normalized binary frame.
+ *  - { action: 'oversize' }    -> caller closes 1009 (message too big)
+ *  - { action: 'unsupported' } -> caller closes 1003 (bad/short/unknown header)
+ *  - { action: 'pcm', pcm }    -> caller hands `pcm` (Buffer) to the STT core
+ *
+ * @param {Buffer} buf  Normalized frame (see normalizeBinaryMessage).
+ * @returns {{action: string, pcm?: Buffer}}
+ */
+function classifyVoiceFrame(buf) {
+  if (buf.length > MAX_VOICE_BINARY_FRAME_BYTES) {
+    return { action: 'oversize' };
+  }
+  if (buf.length < VOICE_HEADER_BYTES
+    || !buf.subarray(0, 4).equals(VOICE_MAGIC)
+    || buf[4] !== VOICE_PROTO_VERSION
+    || buf[5] !== VOICE_FRAME_TYPE_PCM) {
+    return { action: 'unsupported' };
+  }
+  return { action: 'pcm', pcm: buf.subarray(VOICE_HEADER_BYTES) };
+}
+
+module.exports = {
+  VOICE_MAGIC,
+  VOICE_PROTO_VERSION,
+  VOICE_FRAME_TYPE_PCM,
+  VOICE_HEADER_BYTES,
+  MAX_VOICE_PCM_BYTES,
+  MAX_VOICE_BINARY_FRAME_BYTES,
+  normalizeBinaryMessage,
+  classifyVoiceFrame,
+};