@brunobracaioli/aibrain 0.3.0-beta.7 → 0.4.0-beta.2

package/dist/assets/jev-paid-pilot-terminal.mjs

@@ -9,9 +9,16 @@ import { fileURLToPath } from 'node:url';
 import { WebSocketServer, WebSocket } from 'ws';
 
 const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+const MAX_MONITOR_RESPONSE_BYTES = 64 * 1024 * 1024;
+const MAX_MONITOR_PENDING_BYTES = 32 * 1024 * 1024;
 const MAX_QUEUED_FRAMES = 64;
 const MAX_QUEUED_BYTES = 32 * 1024 * 1024;
 const STARTUP_HANDOFF_GRACE_MS = 5_000;
+const MAX_AUXILIARY_CONNECTIONS = 1;
+const MAX_AUXILIARY_MESSAGES = 64;
+const MAX_AUXILIARY_IN_FLIGHT = 32;
+const MAX_AUXILIARY_NOTIFICATIONS = 256;
+const DEFAULT_AUXILIARY_IDLE_TIMEOUT_MS = 120_000;
 const NORMAL_DISCOVERY_CLOSE_CODES = new Set([1000, 1001, 1005]);
 
 function repoRoot() {
@@ -60,7 +67,13 @@ async function main() {
   const codexBinary = process.env.CODEX_BIN ?? 'codex';
   const nativeArgs =
     process.argv.slice(2)[0] === '--' ? process.argv.slice(3) : process.argv.slice(2);
-  const allowStartupHandoff = nativeArgs[0] === 'resume';
+  // The bridge owns an interactive Codex TUI transport. Any native command
+  // that reaches this bridge may perform a short-lived read-only bootstrap
+  // before attaching its conversation transport. The protocol boundary below
+  // is the authority: initialize, same-client identity, successful allowlisted
+  // discovery, no started operation, one candidate, and a five-second deadline.
+  // Non-interactive Codex subcommands never open the socket and exit normally.
+  const allowStartupHandoff = true;
   const childEnv = { ...process.env };
   delete childEnv.JEV_API_KEY;
   delete childEnv.TYPESAFE_API_KEY;
@@ -71,11 +84,19 @@ async function main() {
   const generations = new Set();
   let activeConnection = null;
   let pendingCandidate = null;
+  const auxiliaryConnections = new Set();
   let handoffCount = 0;
   let handoffAttemptCount = 0;
   let socketUpgradeCount = 0;
   let secondConnectionRejectCount = 0;
   let candidateRejectCount = 0;
+  let auxiliaryConnectionCount = 0;
+  let auxiliaryRejectCount = 0;
+  let auxiliaryMutationRejectCount = 0;
+  let auxiliaryUnknownResponseCount = 0;
+  let auxiliaryIdleTimeoutCount = 0;
+  let auxiliaryMessageCount = 0;
+  let auxiliaryNotificationCount = 0;
   let shuttingDown = false;
   const reportPath = process.env.CODEX_TERMINAL_BRIDGE_REPORT;
   let initializeReceived = false;
@@ -86,12 +107,20 @@ async function main() {
   let turnStartCount = 0;
   let threadResumeCount = 0;
   let threadResumeResponseSeen = false;
+  let threadResumeErrorCode = null;
+  let threadResumeErrorCategory = null;
   let handoffInitializeAck = false;
   const observedMethods = new Set();
   const observedThreadIds = new Set();
   let monitorLineCount = 0;
   let monitorByteCount = 0;
   let monitorExitCode = null;
+  let transportAbortReason = null;
+  let transportAbortBytes = null;
+  let transportAbortMethod = null;
+  let maxMonitorFrameBytes = 0;
+  let maxMonitorFrameMethod = null;
+  let outputPauseCount = 0;
   let terminalExitCode = null;
   let server;
   let webSocketServer;
@@ -108,10 +137,12 @@ async function main() {
   };
   const READ_ONLY_DISCOVERY = new Set([
     'account/read',
+    'account/bedrock/checkGovCloudRequirements',
+    'config/read',
+    'configRequirements/read',
     'thread/list',
     'thread/read',
     'model/list',
-    'configRequirements/read',
     'collaborationMode/list',
     'hooks/list',
     'thread/turns/list',
@@ -129,6 +160,8 @@ async function main() {
     'initialize',
     'initialized',
     'account/read',
+    'account/bedrock/checkGovCloudRequirements',
+    'config/read',
     'thread/list',
     'thread/read',
     'model/list',
@@ -164,7 +197,10 @@ async function main() {
       child: null,
       connection: null,
       retiring: false,
-      monitorBuffer: Buffer.alloc(0),
+      monitorFrameParts: [],
+      monitorFrameBytes: 0,
+      monitorPendingChunk: Buffer.alloc(0),
+      monitorPaused: false,
       monitorWritable: true,
       pendingToMonitor: [],
       queuedFrames: 0,
@@ -190,6 +226,10 @@ async function main() {
         rejectCandidate(generation.connection, 1011, 'candidate_monitor_failed');
         return;
       }
+      if (generation.connection?.isAuxiliary) {
+        rejectAuxiliary(generation.connection, 'auxiliary_monitor_failed');
+        return;
+      }
       monitorExitCode = code;
       void cleanup().finally(() => process.exit(code));
     };
@@ -203,22 +243,30 @@ async function main() {
     });
     child.stdout.on('data', (chunk) => {
       if (generation.retiring || shuttingDown) return;
-      generation.monitorBuffer = Buffer.concat([generation.monitorBuffer, Buffer.from(chunk)]);
-      while (true) {
-        const newline = generation.monitorBuffer.indexOf(10);
-        if (newline < 0) break;
-        const line = generation.monitorBuffer.subarray(0, newline);
-        generation.monitorBuffer = generation.monitorBuffer.subarray(newline + 1);
-        handleMonitorLine(generation, line);
-      }
-      if (generation.monitorBuffer.length > MAX_FRAME_BYTES) {
-        abortGeneration(generation, 'monitor_frame_limit');
+      const part = Buffer.from(chunk);
+      if (generation.monitorPaused) {
+        if (generation.monitorPendingChunk.length + part.length > MAX_MONITOR_PENDING_BYTES) {
+          abortGeneration(
+            generation,
+            'monitor_backpressure_limit',
+            generation.monitorPendingChunk.length + part.length,
+          );
+          return;
+        }
+        generation.monitorPendingChunk =
+          generation.monitorPendingChunk.length === 0
+            ? part
+            : Buffer.concat([generation.monitorPendingChunk, part]);
+        return;
       }
+      processMonitorChunk(generation, part);
     });
     child.on('exit', (code) => {
       if (generation.retiring || shuttingDown) {
         generation.pendingToMonitor.length = 0;
-        generation.monitorBuffer = Buffer.alloc(0);
+        generation.monitorFrameParts = [];
+        generation.monitorFrameBytes = 0;
+        generation.monitorPendingChunk = Buffer.alloc(0);
         return;
       }
       fail(code ?? 0);
@@ -227,6 +275,56 @@ async function main() {
   };
 
   let initialGeneration;
+  const resumeMonitor = (generation) => {
+    if (!generation.monitorPaused || generation.retiring || shuttingDown) return;
+    generation.monitorPaused = false;
+    processMonitorBuffer(generation);
+    if (!generation.retiring && !shuttingDown && !generation.monitorPaused)
+      generation.child.stdout.resume();
+  };
+  const pauseMonitor = (generation) => {
+    if (generation.monitorPaused || generation.retiring || shuttingDown) return;
+    generation.monitorPaused = true;
+    outputPauseCount += 1;
+    generation.child.stdout.pause();
+  };
+  const processMonitorChunk = (generation, incoming) => {
+    if (generation.retiring || shuttingDown) return;
+    let offset = 0;
+    while (offset < incoming.length && !generation.monitorPaused && !generation.retiring) {
+      const newline = incoming.indexOf(10, offset);
+      const end = newline < 0 ? incoming.length : newline;
+      const part = incoming.subarray(offset, end);
+      if (generation.monitorFrameBytes + part.length > MAX_MONITOR_RESPONSE_BYTES) {
+        abortGeneration(
+          generation,
+          'monitor_frame_limit',
+          generation.monitorFrameBytes + part.length,
+        );
+        return;
+      }
+      if (part.length > 0) {
+        generation.monitorFrameParts.push(part);
+        generation.monitorFrameBytes += part.length;
+      }
+      offset = newline < 0 ? incoming.length : newline + 1;
+      if (newline >= 0) {
+        const line = Buffer.concat(generation.monitorFrameParts, generation.monitorFrameBytes);
+        generation.monitorFrameParts = [];
+        generation.monitorFrameBytes = 0;
+        handleMonitorLine(generation, line);
+      }
+    }
+    if (offset < incoming.length) generation.monitorPendingChunk = incoming.subarray(offset);
+  };
+  const processMonitorBuffer = (generation) => {
+    if (generation.retiring || shuttingDown) return;
+    if (generation.monitorPendingChunk.length > 0) {
+      const pending = generation.monitorPendingChunk;
+      generation.monitorPendingChunk = Buffer.alloc(0);
+      processMonitorChunk(generation, pending);
+    }
+  };
   const flushGeneration = (generation) => {
     while (generation.monitorWritable && generation.pendingToMonitor.length > 0) {
       const frame = generation.pendingToMonitor.shift();
@@ -258,16 +356,39 @@ async function main() {
     generation.retirementTimer = setTimeout(() => {
       killOwned(generation.child, 'SIGKILL');
       generation.pendingToMonitor.length = 0;
-      generation.monitorBuffer = Buffer.alloc(0);
+      generation.monitorFrameParts = [];
+      generation.monitorFrameBytes = 0;
+      generation.monitorPendingChunk = Buffer.alloc(0);
       generations.delete(generation);
     }, 500);
   };
-  const abortGeneration = (generation, reason) => {
+  const abortGeneration = (generation, reason, bytes = null, method = null) => {
     const connection = generation.connection;
+    const primaryConnection = connection?.isCandidate !== true && connection?.isAuxiliary !== true;
+    if (transportAbortReason === null || primaryConnection) {
+      transportAbortReason = reason;
+      transportAbortBytes = Number.isSafeInteger(bytes) ? bytes : null;
+      transportAbortMethod = typeof method === 'string' ? method : null;
+    }
+    if (primaryConnection && cleanupInitiator === 'unknown') {
+      cleanupInitiator = `transport_${reason}`;
+      process.stderr.write(
+        `${JSON.stringify({
+          event: 'codex_terminal_bridge_error',
+          category: reason,
+          ...(transportAbortBytes === null ? {} : { bytes: transportAbortBytes }),
+          ...(transportAbortMethod === null ? {} : { method: transportAbortMethod }),
+        })}\n`,
+      );
+    }
     if (connection?.isCandidate) {
       rejectCandidate(connection, 1013, reason);
       return;
     }
+    if (connection?.isAuxiliary) {
+      rejectAuxiliary(connection, reason);
+      return;
+    }
     if (connection) connection.retiring = true;
     cleanupGeneration(generation);
     connection?.socket.close(1013, reason);
@@ -308,7 +429,7 @@ async function main() {
         ),
         new Promise((resolve) => setTimeout(resolve, 500)),
       ]);
-      for (const connection of [activeConnection, pendingCandidate]) {
+      for (const connection of [activeConnection, pendingCandidate, ...auxiliaryConnections]) {
         if (connection?.socket.readyState === WebSocket.OPEN)
           connection.socket.close(1001, 'bridge stopped');
         connection?.socket.terminate();
@@ -333,12 +454,20 @@ async function main() {
             turn_start_count: turnStartCount,
             thread_resume_count: threadResumeCount,
             thread_resume_response_seen: threadResumeResponseSeen,
+            thread_resume_error_code: threadResumeErrorCode,
+            thread_resume_error_category: threadResumeErrorCategory,
             handoff_initialize_ack: handoffInitializeAck,
             observed_methods: [...observedMethods],
             observed_thread_ids: [...observedThreadIds],
             monitor_line_count: monitorLineCount,
             monitor_byte_count: monitorByteCount,
             monitor_exit_code: monitorExitCode,
+            transport_abort_reason: transportAbortReason,
+            transport_abort_bytes: transportAbortBytes,
+            transport_abort_method: transportAbortMethod,
+            max_monitor_frame_bytes: maxMonitorFrameBytes,
+            max_monitor_frame_method: maxMonitorFrameMethod,
+            output_pause_count: outputPauseCount,
             terminal_exit_code: terminalExitCode,
             handoff_count: handoffCount,
             handoff_attempt_count: handoffAttemptCount,
@@ -346,6 +475,13 @@ async function main() {
             socket_upgrade_count: socketUpgradeCount,
             second_connection_reject_count: secondConnectionRejectCount,
             candidate_reject_count: candidateRejectCount,
+            auxiliary_connection_count: auxiliaryConnectionCount,
+            auxiliary_reject_count: auxiliaryRejectCount,
+            auxiliary_mutation_reject_count: auxiliaryMutationRejectCount,
+            auxiliary_unknown_response_count: auxiliaryUnknownResponseCount,
+            auxiliary_idle_timeout_count: auxiliaryIdleTimeoutCount,
+            auxiliary_message_count: auxiliaryMessageCount,
+            auxiliary_notification_count: auxiliaryNotificationCount,
             cleanup_initiator: cleanupInitiator,
             last_socket_close_code: lastSocketCloseCode,
             terminal_alive_at_socket_close: terminalAliveAtSocketClose,
@@ -406,6 +542,24 @@ async function main() {
     connection.initialized === true &&
     connection.initializeAck === true &&
     (connection.socket.readyState === WebSocket.OPEN || connection.discoveryClosed === true);
+  const auxiliaryIdleTimeoutMs = (() => {
+    const value = Number.parseInt(process.env.CODEX_AUXILIARY_IDLE_TIMEOUT_MS ?? '', 10);
+    return Number.isSafeInteger(value) && value >= 1_000 && value <= 300_000
+      ? value
+      : DEFAULT_AUXILIARY_IDLE_TIMEOUT_MS;
+  })();
+  const rejectAuxiliary = (connection, reason = 'auxiliary_rejected') => {
+    if (!connection || connection.retiring || !connection.isAuxiliary) return;
+    connection.retiring = true;
+    if (connection.auxiliaryTimer !== null) clearTimeout(connection.auxiliaryTimer);
+    auxiliaryConnections.delete(connection);
+    auxiliaryRejectCount += 1;
+    if (reason === 'auxiliary_idle_timeout') auxiliaryIdleTimeoutCount += 1;
+    if (connection.socket.readyState === WebSocket.OPEN)
+      connection.socket.close(1008, reason);
+    else connection.socket.terminate();
+    cleanupGeneration(connection.generation);
+  };
   const rejectCandidate = (connection, statusCode = 1008, reason = 'handoff_rejected') => {
     if (!connection || connection.retiring) return;
     if (connection?.candidateTimer) clearTimeout(connection.candidateTimer);
@@ -463,14 +617,20 @@ async function main() {
     if (line.length === 0) return;
     const connection = generation.connection;
     if (!connection || connection.retiring) return;
-    if (line.length > MAX_FRAME_BYTES) {
-      abortGeneration(generation, 'monitor_frame_limit');
+    if (line.length > MAX_MONITOR_RESPONSE_BYTES) {
+      abortGeneration(generation, 'monitor_frame_limit', line.length);
       return;
     }
     let parsed;
+    let responseMethod;
     try {
       parsed = JSON.parse(line.toString('utf8'));
-      if (connection.initializeId !== null && parsed.id === connection.initializeId) {
+      const isInitializeResponse =
+        connection.initializeId !== null &&
+        parsed.id === connection.initializeId &&
+        connection.initializeResponseConsumed === false;
+      if (isInitializeResponse) {
+        connection.initializeResponseConsumed = true;
         initializeResponseSeen = true;
         initializeErrorCode = parsed.error?.code ?? null;
         if (parsed.error === undefined && parsed.result !== undefined) {
@@ -497,12 +657,32 @@ async function main() {
       const isJsonRpcResponse =
         Object.prototype.hasOwnProperty.call(parsed, 'result') ||
         Object.prototype.hasOwnProperty.call(parsed, 'error');
+      if (connection.isAuxiliary && parsed.method !== undefined && parsed.id === undefined) {
+        auxiliaryNotificationCount += 1;
+        connection.auxiliaryNotificationCount += 1;
+        if (connection.auxiliaryNotificationCount > MAX_AUXILIARY_NOTIFICATIONS) {
+          rejectAuxiliary(connection, 'auxiliary_notification_limit');
+        }
+        return;
+      }
+      if (
+        connection.isAuxiliary &&
+        (parsed.method !== undefined ||
+          (isJsonRpcResponse &&
+            !isInitializeResponse &&
+            !connection.pendingRequests.has(parsed.id)))
+      ) {
+        auxiliaryUnknownResponseCount += 1;
+        rejectAuxiliary(connection, 'auxiliary_response_rejected');
+        return;
+      }
       if (
         isJsonRpcResponse &&
         parsed.id !== undefined &&
         connection.pendingRequests.has(parsed.id)
       ) {
         const method = connection.pendingRequests.get(parsed.id);
+        responseMethod = method;
         connection.pendingRequests.delete(parsed.id);
         if (parsed.error === undefined && PRIMARY_DISCOVERY.has(method)) {
           connection.discoverySatisfied = true;
@@ -516,16 +696,45 @@ async function main() {
       ) {
         connection.threadResumeRequestIds.delete(parsed.id);
         if (parsed.error === undefined) threadResumeResponseSeen = true;
+        else {
+          if (Number.isSafeInteger(parsed.error?.code)) threadResumeErrorCode = parsed.error.code;
+          const message =
+            typeof parsed.error?.message === 'string' ? parsed.error.message.toLowerCase() : '';
+          threadResumeErrorCategory = /no.?rollout|rollout.*not.?found/u.test(message)
+            ? 'no_rollout_found'
+            : /thread.*not.?found|unknown.*thread/u.test(message)
+              ? 'thread_not_found'
+              : /sqlite|database|locked|busy/u.test(message)
+                ? 'database_state'
+                : /config|invalid.*param|parameter/u.test(message)
+                  ? 'protocol_configuration'
+                  : /model|provider|auth|credential/u.test(message)
+                    ? 'model_or_auth'
+                    : 'native_internal_error';
+        }
+      }
+      if (line.length > maxMonitorFrameBytes) {
+        maxMonitorFrameBytes = line.length;
+        maxMonitorFrameMethod = responseMethod ?? null;
       }
     } catch {
-      parsed = null;
+      abortGeneration(generation, 'monitor_frame_invalid', line.length, responseMethod);
+      return;
     }
-    if (connection.socket.readyState !== WebSocket.OPEN) return;
-    if (connection.socket.bufferedAmount + line.length > MAX_QUEUED_BYTES) {
-      abortGeneration(generation, 'bridge_queue_limit');
+    if (connection.isAuxiliary && parsed === null) {
+      auxiliaryUnknownResponseCount += 1;
+      rejectAuxiliary(connection, 'auxiliary_response_rejected');
       return;
     }
-    connection.socket.send(line.toString('utf8'), { binary: false });
+    if (connection.socket.readyState !== WebSocket.OPEN) return;
+    pauseMonitor(generation);
+    connection.socket.send(line.toString('utf8'), { binary: false }, (error) => {
+      if (error && !generation.retiring && !shuttingDown) {
+        abortGeneration(generation, 'bridge_output_failed', line.length, responseMethod);
+        return;
+      }
+      resumeMonitor(generation);
+    });
   };
   const handleClientMessage = (connection, data, isBinary) => {
     if (shuttingDown) return;
@@ -535,18 +744,29 @@ async function main() {
       const parsed = JSON.parse(frame.toString('utf8'));
       if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
         throw new Error('bridge_message_not_object');
+      if (
+        connection.isAuxiliary &&
+        (typeof parsed.method !== 'string' ||
+          Object.prototype.hasOwnProperty.call(parsed, 'result') ||
+          Object.prototype.hasOwnProperty.call(parsed, 'error'))
+      ) {
+        auxiliaryMutationRejectCount += 1;
+        rejectAuxiliary(connection, 'auxiliary_client_frame_rejected');
+        return;
+      }
       const normalizedFrame = Buffer.from(JSON.stringify(parsed), 'utf8');
+      const wasInitialized = connection.initialized;
       if (!connection.initialized) {
         const initialize = parseInitialize(normalizedFrame.toString('utf8'));
         if (
-          connection.isCandidate &&
+          (connection.isCandidate || connection.isAuxiliary) &&
           !sameClient(activeConnection?.clientInfo, initialize.params.clientInfo)
         )
           throw new Error('handoff_client_mismatch');
         connection.initialized = true;
         connection.initializeId = initialize.id;
         connection.clientInfo = initialize.params.clientInfo;
-        if (!connection.isCandidate) {
+        if (!connection.isCandidate && !connection.isAuxiliary) {
           initializeReceived = true;
           experimentalApi = initialize.params.capabilities.experimentalApi === true;
         }
@@ -555,8 +775,30 @@ async function main() {
           connection.generation = spawnMonitor();
           connection.generation.connection = connection;
         }
+        if (connection.isAuxiliary && connection.generation === null) {
+          connection.generation = spawnMonitor();
+          connection.generation.connection = connection;
+        }
+      }
+      if (connection.isAuxiliary) {
+        auxiliaryMessageCount += 1;
+        connection.auxiliaryMessageCount += 1;
+        if (connection.auxiliaryMessageCount > MAX_AUXILIARY_MESSAGES) {
+          rejectAuxiliary(connection, 'auxiliary_message_limit');
+          return;
+        }
+        if (connection.auxiliaryTimer !== null) clearTimeout(connection.auxiliaryTimer);
+        connection.auxiliaryTimer = setTimeout(
+          () => rejectAuxiliary(connection, 'auxiliary_idle_timeout'),
+          auxiliaryIdleTimeoutMs,
+        );
       }
-      if (parsed.method === 'turn/start') turnStartCount += 1;
+      if (connection.isAuxiliary && wasInitialized && parsed.method === 'initialize') {
+        auxiliaryMutationRejectCount += 1;
+        rejectAuxiliary(connection, 'auxiliary_duplicate_initialize');
+        return;
+      }
+      if (parsed.method === 'turn/start' && !connection.isAuxiliary) turnStartCount += 1;
       if (typeof parsed.method === 'string') {
         if (DIAGNOSTIC_METHODS.has(parsed.method)) {
           if (observedMethods.size < MAX_DIAGNOSTIC_ENTRIES) observedMethods.add(parsed.method);
@@ -565,7 +807,33 @@ async function main() {
         }
         if (parsed.method === 'thread/resume') threadResumeCount += 1;
         if (parsed.method === 'initialize' || parsed.method === 'initialized') {
+          if (connection.isAuxiliary && parsed.method === 'initialized') {
+            if (connection.initializedNotificationSeen) {
+              auxiliaryMutationRejectCount += 1;
+              rejectAuxiliary(connection, 'auxiliary_duplicate_initialized');
+              return;
+            }
+            connection.initializedNotificationSeen = true;
+          }
           // The notification is part of the handshake and does not affect startup eligibility.
+        } else if (connection.isAuxiliary) {
+          if (!READ_ONLY_DISCOVERY.has(parsed.method)) {
+            auxiliaryMutationRejectCount += 1;
+            rejectAuxiliary(connection, 'auxiliary_mutation_rejected');
+            return;
+          }
+          const validRequestId =
+            (typeof parsed.id === 'string' && parsed.id.length > 0 && parsed.id.length <= 128) ||
+            (Number.isSafeInteger(parsed.id) && parsed.id >= 0);
+          if (
+            !validRequestId ||
+            connection.pendingRequests.has(parsed.id) ||
+            connection.pendingRequests.size >= MAX_AUXILIARY_IN_FLIGHT
+          ) {
+            rejectAuxiliary(connection, 'auxiliary_request_limit');
+            return;
+          }
+          connection.pendingRequests.set(parsed.id, parsed.method);
         } else if (READ_ONLY_DISCOVERY.has(parsed.method)) {
           const validRequestId =
             (typeof parsed.id === 'string' && parsed.id.length > 0 && parsed.id.length <= 128) ||
@@ -607,18 +875,22 @@ async function main() {
       }
     } catch (error) {
       if (connection.isCandidate) rejectCandidate(connection, 1008, safeError(error));
+      else if (connection.isAuxiliary) rejectAuxiliary(connection, safeError(error));
       else connection.socket.close(1008, safeError(error));
     }
   };
-  const attachConnection = (webSocket, isCandidate) => {
+  const attachConnection = (webSocket, isCandidate, isAuxiliary = false) => {
     const connection = {
       socket: webSocket,
-      generation: isCandidate ? null : initialGeneration,
+      generation: isCandidate || isAuxiliary ? null : initialGeneration,
       isCandidate,
-      isActive: !isCandidate,
+      isAuxiliary,
+      isActive: !isCandidate && !isAuxiliary,
       retiring: false,
       initialized: false,
       initializeId: null,
+      initializeResponseConsumed: false,
+      initializedNotificationSeen: false,
       initializeAck: false,
       clientInfo: null,
       pendingRequests: new Map(),
@@ -631,15 +903,27 @@ async function main() {
       handoffComplete: false,
       discoveryClosed: false,
       candidateTimer: null,
+      auxiliaryTimer: null,
+      auxiliaryMessageCount: 0,
+      auxiliaryNotificationCount: 0,
     };
-    if (!isCandidate) {
+    if (!isCandidate && !isAuxiliary) {
       activeConnection = connection;
       initialGeneration.connection = connection;
     }
+    if (isAuxiliary) {
+      auxiliaryConnections.add(connection);
+      auxiliaryConnectionCount += 1;
+      connection.auxiliaryTimer = setTimeout(
+        () => rejectAuxiliary(connection, 'auxiliary_idle_timeout'),
+        auxiliaryIdleTimeoutMs,
+      );
+    }
     webSocket.on('message', (data, isBinary) => handleClientMessage(connection, data, isBinary));
     webSocket.on('error', () => {
       if (connection.retiring || shuttingDown) return;
       if (connection.isCandidate) rejectCandidate(connection, 1011, 'candidate_socket_error');
+      else if (connection.isAuxiliary) rejectAuxiliary(connection, 'auxiliary_socket_error');
       else {
         cleanupInitiator = 'socket_error';
         recordLifecycle('socket_error');
@@ -652,6 +936,12 @@ async function main() {
       lastSocketCloseCode = code;
       terminalAliveAtSocketClose = terminal?.exitCode === null;
       recordLifecycle('socket_close');
+      if (connection.isAuxiliary) {
+        if (connection.auxiliaryTimer !== null) clearTimeout(connection.auxiliaryTimer);
+        auxiliaryConnections.delete(connection);
+        cleanupGeneration(connection.generation);
+        return;
+      }
       if (connection.isCandidate) {
         rejectCandidate(connection);
         return;
@@ -705,14 +995,23 @@ async function main() {
       closeSocket(socket, 403, 'origin_rejected');
       return;
     }
-    const isCandidate = activeConnection !== null;
-    if (isCandidate && !canHandoff(activeConnection)) {
+    const isCandidate = activeConnection !== null && canHandoff(activeConnection);
+    const isAuxiliary =
+      activeConnection !== null &&
+      !isCandidate &&
+      activeConnection.initialized === true &&
+      activeConnection.startedOperation === true;
+    if (
+      activeConnection !== null &&
+      !isCandidate &&
+      (!isAuxiliary || auxiliaryConnections.size >= MAX_AUXILIARY_CONNECTIONS)
+    ) {
       secondConnectionRejectCount += 1;
       closeSocket(socket, 409, 'second_connection_rejected');
       return;
     }
     webSocketServer.handleUpgrade(request, socket, head, (webSocket) => {
-      const connection = attachConnection(webSocket, isCandidate);
+      const connection = attachConnection(webSocket, isCandidate, isAuxiliary);
       if (isCandidate) {
         pendingCandidate = connection;
         connection.candidateTimer = setTimeout(