@brunobracaioli/aibrain 0.2.0-beta.1 → 0.3.0-beta.7

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

@@ -11,6 +11,8 @@ import { WebSocketServer, WebSocket } from 'ws';
 const MAX_FRAME_BYTES = 16 * 1024 * 1024;
 const MAX_QUEUED_FRAMES = 64;
 const MAX_QUEUED_BYTES = 32 * 1024 * 1024;
+const STARTUP_HANDOFF_GRACE_MS = 5_000;
+const NORMAL_DISCOVERY_CLOSE_CODES = new Set([1000, 1001, 1005]);
 
 function repoRoot() {
   return fileURLToPath(new URL('..', import.meta.url)).replace(/\/$/u, '');
@@ -54,28 +56,38 @@ async function main() {
   const root = repoRoot();
   const monitorCommand =
     process.env.CODEX_MONITOR_COMMAND ?? join(root, 'scripts/jev-paid-pilot-codex.sh');
+  const monitorCwd = process.env.CODEX_MONITOR_CWD ?? process.cwd();
   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';
   const childEnv = { ...process.env };
   delete childEnv.JEV_API_KEY;
   delete childEnv.TYPESAFE_API_KEY;
   const bridgeRoot = await mkdtemp(join(tmpdir(), 'ai-brain-codex-terminal-'));
   await chmod(bridgeRoot, 0o700);
   const socketPath = join(bridgeRoot, 'codex.sock');
-  let monitor = null;
   let terminal = null;
-  let activeSocket = null;
-  let accepted = false;
+  const generations = new Set();
+  let activeConnection = null;
+  let pendingCandidate = null;
+  let handoffCount = 0;
+  let handoffAttemptCount = 0;
+  let socketUpgradeCount = 0;
+  let secondConnectionRejectCount = 0;
+  let candidateRejectCount = 0;
   let shuttingDown = false;
   const reportPath = process.env.CODEX_TERMINAL_BRIDGE_REPORT;
   let initializeReceived = false;
   let experimentalApi = false;
-  let initializeId = null;
   let initializeAck = false;
   let initializeResponseSeen = false;
   let initializeErrorCode = null;
   let turnStartCount = 0;
+  let threadResumeCount = 0;
+  let threadResumeResponseSeen = false;
+  let handoffInitializeAck = false;
+  const observedMethods = new Set();
   const observedThreadIds = new Set();
   let monitorLineCount = 0;
   let monitorByteCount = 0;
@@ -84,6 +96,59 @@ async function main() {
   let server;
   let webSocketServer;
   let cleanupPromise = null;
+  let failureReported = false;
+  let startupGraceTimer = null;
+  let cleanupInitiator = 'unknown';
+  let lastSocketCloseCode = null;
+  let terminalAliveAtSocketClose = null;
+  let terminalExitSignal = null;
+  const lifecycleEvents = [];
+  const recordLifecycle = (event) => {
+    if (lifecycleEvents.length < 32) lifecycleEvents.push(event);
+  };
+  const READ_ONLY_DISCOVERY = new Set([
+    'account/read',
+    'thread/list',
+    'thread/read',
+    'model/list',
+    'configRequirements/read',
+    'collaborationMode/list',
+    'hooks/list',
+    'thread/turns/list',
+    'thread/items/list',
+    'thread/loaded/list',
+    'thread/goal/get',
+    'skills/list',
+    'plugin/list',
+    'app/installed',
+  ]);
+  const PRIMARY_DISCOVERY = new Set(['account/read', 'thread/list', 'thread/read']);
+  const MAX_PENDING_DISCOVERY = 128;
+  const MAX_DIAGNOSTIC_ENTRIES = 128;
+  const DIAGNOSTIC_METHODS = new Set([
+    'initialize',
+    'initialized',
+    'account/read',
+    'thread/list',
+    'thread/read',
+    'model/list',
+    'configRequirements/read',
+    'collaborationMode/list',
+    'hooks/list',
+    'thread/turns/list',
+    'thread/items/list',
+    'thread/loaded/list',
+    'thread/goal/get',
+    'skills/list',
+    'plugin/list',
+    'app/installed',
+    'thread/resume',
+    'thread/start',
+    'thread/fork',
+    'turn/start',
+    'thread/unsubscribe',
+  ]);
+  let unknownMethodCount = 0;
   const killOwned = (child, signal) => {
     if (!child) return;
     try {
@@ -94,28 +159,160 @@ async function main() {
     }
   };
 
+  const spawnMonitor = () => {
+    const generation = {
+      child: null,
+      connection: null,
+      retiring: false,
+      monitorBuffer: Buffer.alloc(0),
+      monitorWritable: true,
+      pendingToMonitor: [],
+      queuedFrames: 0,
+      queuedBytes: 0,
+      retirementTimer: null,
+    };
+    const child = spawn(monitorCommand, [], {
+      cwd: monitorCwd,
+      env: childEnv,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+    generation.child = child;
+    generations.add(generation);
+    // Native app-server diagnostics may contain terminal control sequences or
+    // private operational text. Keep the monitor outside the user's TTY while
+    // preserving protocol frames and child exit/error handling separately.
+    child.stderr?.on('data', () => undefined);
+    child.stderr?.resume?.();
+    const fail = (code = 1) => {
+      if (shuttingDown || generation.retiring) return;
+      if (generation.connection?.isCandidate) {
+        rejectCandidate(generation.connection, 1011, 'candidate_monitor_failed');
+        return;
+      }
+      monitorExitCode = code;
+      void cleanup().finally(() => process.exit(code));
+    };
+    child.on('error', () => fail(1));
+    child.stdin.on('error', () => fail(1));
+    child.stdout.on('error', () => fail(1));
+    child.stdin.on('drain', () => {
+      if (generation.retiring || shuttingDown) return;
+      generation.monitorWritable = true;
+      flushGeneration(generation);
+    });
+    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');
+      }
+    });
+    child.on('exit', (code) => {
+      if (generation.retiring || shuttingDown) {
+        generation.pendingToMonitor.length = 0;
+        generation.monitorBuffer = Buffer.alloc(0);
+        return;
+      }
+      fail(code ?? 0);
+    });
+    return generation;
+  };
+
+  let initialGeneration;
+  const flushGeneration = (generation) => {
+    while (generation.monitorWritable && generation.pendingToMonitor.length > 0) {
+      const frame = generation.pendingToMonitor.shift();
+      generation.queuedFrames -= 1;
+      generation.queuedBytes -= frame.length;
+      generation.monitorWritable = generation.child.stdin.write(`${frame.toString('utf8')}\n`);
+    }
+  };
+
+  const enqueueForMonitor = (connection, frame) => {
+    const generation = connection.generation;
+    if (generation === null || generation.retiring) throw new Error('bridge_monitor_unavailable');
+    if (
+      frame.length > MAX_FRAME_BYTES ||
+      generation.queuedFrames >= MAX_QUEUED_FRAMES ||
+      generation.queuedBytes + frame.length > MAX_QUEUED_BYTES
+    )
+      throw new Error('bridge_queue_limit');
+    generation.pendingToMonitor.push(frame);
+    generation.queuedFrames += 1;
+    generation.queuedBytes += frame.length;
+    flushGeneration(generation);
+  };
+
+  const cleanupGeneration = (generation) => {
+    if (!generation || generation.retiring) return;
+    generation.retiring = true;
+    killOwned(generation.child, 'SIGTERM');
+    generation.retirementTimer = setTimeout(() => {
+      killOwned(generation.child, 'SIGKILL');
+      generation.pendingToMonitor.length = 0;
+      generation.monitorBuffer = Buffer.alloc(0);
+      generations.delete(generation);
+    }, 500);
+  };
+  const abortGeneration = (generation, reason) => {
+    const connection = generation.connection;
+    if (connection?.isCandidate) {
+      rejectCandidate(connection, 1013, reason);
+      return;
+    }
+    if (connection) connection.retiring = true;
+    cleanupGeneration(generation);
+    connection?.socket.close(1013, reason);
+    void cleanup().finally(() => process.exit(1));
+  };
+  const clearStartupGrace = () => {
+    if (startupGraceTimer !== null) clearTimeout(startupGraceTimer);
+    startupGraceTimer = null;
+  };
+  const armStartupGrace = (connection) => {
+    if (startupGraceTimer !== null || !allowStartupHandoff || terminal?.exitCode !== null) return;
+    recordLifecycle('startup_grace_started');
+    startupGraceTimer = setTimeout(() => {
+      startupGraceTimer = null;
+      if (!shuttingDown && activeConnection === connection && terminal?.exitCode === null) {
+        recordLifecycle('startup_handoff_timeout');
+        failBridge('startup_handoff_timeout');
+      }
+    }, STARTUP_HANDOFF_GRACE_MS);
+  };
+
   const cleanup = () => {
     if (cleanupPromise) return cleanupPromise;
     cleanupPromise = (async () => {
       shuttingDown = true;
-      for (const child of [terminal, monitor]) {
-        killOwned(child, 'SIGTERM');
-      }
+      recordLifecycle('cleanup_started');
+      clearStartupGrace();
+      for (const generation of generations) cleanupGeneration(generation);
+      killOwned(terminal, 'SIGTERM');
       await new Promise((resolve) => setTimeout(resolve, 500));
-      for (const child of [terminal, monitor]) {
-        killOwned(child, 'SIGKILL');
-      }
+      for (const generation of generations) killOwned(generation.child, 'SIGKILL');
+      killOwned(terminal, 'SIGKILL');
       await Promise.race([
         Promise.all(
-          [terminal, monitor]
+          [terminal, ...[...generations].map((generation) => generation.child)]
             .filter((child) => child?.exitCode === null)
             .map((child) => new Promise((resolve) => child.once('exit', resolve))),
         ),
         new Promise((resolve) => setTimeout(resolve, 500)),
       ]);
-      if (activeSocket && activeSocket.readyState === WebSocket.OPEN)
-        activeSocket.close(1001, 'bridge stopped');
-      activeSocket?.terminate();
+      for (const connection of [activeConnection, pendingCandidate]) {
+        if (connection?.socket.readyState === WebSocket.OPEN)
+          connection.socket.close(1001, 'bridge stopped');
+        connection?.socket.terminate();
+      }
       if (server)
         await Promise.race([
           new Promise((resolve) => server.close(() => resolve())),
@@ -134,11 +331,26 @@ async function main() {
             initialize_response_seen: initializeResponseSeen,
             initialize_error_code: initializeErrorCode,
             turn_start_count: turnStartCount,
+            thread_resume_count: threadResumeCount,
+            thread_resume_response_seen: threadResumeResponseSeen,
+            handoff_initialize_ack: handoffInitializeAck,
+            observed_methods: [...observedMethods],
             observed_thread_ids: [...observedThreadIds],
             monitor_line_count: monitorLineCount,
             monitor_byte_count: monitorByteCount,
             monitor_exit_code: monitorExitCode,
             terminal_exit_code: terminalExitCode,
+            handoff_count: handoffCount,
+            handoff_attempt_count: handoffAttemptCount,
+            unknown_method_count: unknownMethodCount,
+            socket_upgrade_count: socketUpgradeCount,
+            second_connection_reject_count: secondConnectionRejectCount,
+            candidate_reject_count: candidateRejectCount,
+            cleanup_initiator: cleanupInitiator,
+            last_socket_close_code: lastSocketCloseCode,
+            terminal_alive_at_socket_close: terminalAliveAtSocketClose,
+            terminal_exit_signal: terminalExitSignal,
+            lifecycle_events: lifecycleEvents,
             cleanup_complete: true,
           })}\n`,
           { mode: 0o600, flag: 'wx' },
@@ -147,23 +359,22 @@ async function main() {
     return cleanupPromise;
   };
 
-  const shutdown = () => void cleanup().finally(() => process.exit(0));
+  const shutdown = () => {
+    cleanupInitiator = 'signal';
+    clearStartupGrace();
+    void cleanup().finally(() => process.exit(0));
+  };
+  const failBridge = (category) => {
+    if (failureReported || shuttingDown) return;
+    failureReported = true;
+    cleanupInitiator = category;
+    process.stderr.write(`${JSON.stringify({ event: 'codex_terminal_bridge_error', category })}\n`);
+    void cleanup().finally(() => process.exit(1));
+  };
   process.once('SIGINT', shutdown);
   process.once('SIGTERM', shutdown);
 
-  monitor = spawn(monitorCommand, [], {
-    cwd: process.cwd(),
-    env: childEnv,
-    stdio: ['pipe', 'pipe', 'inherit'],
-    detached: process.platform !== 'win32',
-  });
-  monitor.on('error', () => void cleanup().finally(() => process.exit(1)));
-  monitor.stdin.on('error', () => void cleanup().finally(() => process.exit(1)));
-  monitor.stdout.on('error', () => void cleanup().finally(() => process.exit(1)));
-  monitor.on('exit', (code) => {
-    monitorExitCode = code;
-    if (!shuttingDown) void cleanup().finally(() => process.exit(code ?? 0));
-  });
+  initialGeneration = spawnMonitor();
 
   server = createServer((_request, response) => {
     response.writeHead(404);
@@ -174,111 +385,341 @@ async function main() {
     maxPayload: MAX_FRAME_BYTES,
     perMessageDeflate: false,
   });
-  server.on('upgrade', (request, socket, head) => {
-    if (request.headers.origin !== undefined) {
-      closeSocket(socket, 403, 'origin_rejected');
+  const sameClient = (left, right) => {
+    const leftInfo = left ?? {};
+    const rightInfo = right ?? {};
+    const hasOriginalIdentity = ['name', 'version'].some((key) => leftInfo[key] !== undefined);
+    if (!hasOriginalIdentity) return true;
+    if (!right) return false;
+    for (const key of ['name', 'version']) {
+      if (leftInfo[key] !== undefined && rightInfo?.[key] !== leftInfo[key]) return false;
+    }
+    return true;
+  };
+  const canHandoff = (connection) =>
+    !shuttingDown &&
+    allowStartupHandoff &&
+    handoffAttemptCount === 0 &&
+    pendingCandidate === null &&
+    connection?.handoffEligible === true &&
+    connection.startedOperation === false &&
+    connection.initialized === true &&
+    connection.initializeAck === true &&
+    (connection.socket.readyState === WebSocket.OPEN || connection.discoveryClosed === true);
+  const rejectCandidate = (connection, statusCode = 1008, reason = 'handoff_rejected') => {
+    if (!connection || connection.retiring) return;
+    if (connection?.candidateTimer) clearTimeout(connection.candidateTimer);
+    if (pendingCandidate === connection) pendingCandidate = null;
+    candidateRejectCount += 1;
+    connection.retiring = true;
+    connection.pendingClientFrames.length = 0;
+    connection.pendingClientBytes = 0;
+    cleanupGeneration(connection.generation);
+    if (connection.socket.readyState === WebSocket.OPEN)
+      connection.socket.close(statusCode, reason);
+    else connection.socket.terminate();
+    if (activeConnection?.socket.readyState !== WebSocket.OPEN && pendingCandidate === null)
+      failBridge('startup_handoff_failed');
+  };
+  const retireConnection = (connection) => {
+    if (!connection) return;
+    connection.retiring = true;
+    if (connection.candidateTimer) clearTimeout(connection.candidateTimer);
+    cleanupGeneration(connection.generation);
+    if (connection.socket.readyState === WebSocket.OPEN)
+      connection.socket.close(1001, 'startup handoff');
+    connection.socket.terminate();
+  };
+  const completeHandoff = (candidate) => {
+    if (candidate.retiring || pendingCandidate !== candidate || candidate.initializeAck !== true)
+      return;
+    candidate.handoffComplete = true;
+    if (candidate.candidateTimer) clearTimeout(candidate.candidateTimer);
+    const previous = activeConnection;
+    if (
+      previous === null ||
+      previous.handoffEligible !== true ||
+      previous.startedOperation === true
+    ) {
+      rejectCandidate(candidate, 1008, 'handoff_no_longer_eligible');
       return;
     }
-    if (accepted) {
-      closeSocket(socket, 409, 'second_connection_rejected');
+    pendingCandidate = null;
+    handoffCount += 1;
+    clearStartupGrace();
+    recordLifecycle('handoff_ack');
+    if (previous) retireConnection(previous);
+    activeConnection = candidate;
+    candidate.isCandidate = false;
+    candidate.isActive = true;
+    const pendingFrames = candidate.pendingClientFrames.splice(0);
+    candidate.pendingClientBytes = 0;
+    for (const frame of pendingFrames) enqueueForMonitor(candidate, frame);
+  };
+  const handleMonitorLine = (generation, line) => {
+    if (shuttingDown) return;
+    monitorLineCount += 1;
+    monitorByteCount += line.length + 1;
+    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');
       return;
     }
-    webSocketServer.handleUpgrade(request, socket, head, (webSocket) => {
-      accepted = true;
-      activeSocket = webSocket;
-      let initialized = false;
-      let queuedFrames = 0;
-      let queuedBytes = 0;
-      const pendingToMonitor = [];
-      let monitorWritable = true;
-      const flush = () => {
-        while (monitorWritable && pendingToMonitor.length > 0) {
-          const frame = pendingToMonitor.shift();
-          queuedFrames -= 1;
-          queuedBytes -= frame.length;
-          monitorWritable = monitor.stdin.write(`${frame.toString('utf8')}\n`);
+    let parsed;
+    try {
+      parsed = JSON.parse(line.toString('utf8'));
+      if (connection.initializeId !== null && parsed.id === connection.initializeId) {
+        initializeResponseSeen = true;
+        initializeErrorCode = parsed.error?.code ?? null;
+        if (parsed.error === undefined && parsed.result !== undefined) {
+          initializeAck = true;
+          connection.initializeAck = true;
+          if (connection.isCandidate) {
+            handoffInitializeAck = true;
+            completeHandoff(connection);
+          }
+        }
+      }
+      if (
+        typeof parsed.params?.threadId === 'string' &&
+        parsed.params.threadId.length <= 128 &&
+        observedThreadIds.size < MAX_DIAGNOSTIC_ENTRIES
+      )
+        observedThreadIds.add(parsed.params.threadId);
+      if (
+        typeof parsed.result?.thread?.id === 'string' &&
+        parsed.result.thread.id.length <= 128 &&
+        observedThreadIds.size < MAX_DIAGNOSTIC_ENTRIES
+      )
+        observedThreadIds.add(parsed.result.thread.id);
+      const isJsonRpcResponse =
+        Object.prototype.hasOwnProperty.call(parsed, 'result') ||
+        Object.prototype.hasOwnProperty.call(parsed, 'error');
+      if (
+        isJsonRpcResponse &&
+        parsed.id !== undefined &&
+        connection.pendingRequests.has(parsed.id)
+      ) {
+        const method = connection.pendingRequests.get(parsed.id);
+        connection.pendingRequests.delete(parsed.id);
+        if (parsed.error === undefined && PRIMARY_DISCOVERY.has(method)) {
+          connection.discoverySatisfied = true;
+          if (!connection.startedOperation) connection.handoffEligible = true;
+        }
+      }
+      if (
+        isJsonRpcResponse &&
+        parsed.id !== undefined &&
+        connection.threadResumeRequestIds.has(parsed.id)
+      ) {
+        connection.threadResumeRequestIds.delete(parsed.id);
+        if (parsed.error === undefined) threadResumeResponseSeen = true;
+      }
+    } catch {
+      parsed = null;
+    }
+    if (connection.socket.readyState !== WebSocket.OPEN) return;
+    if (connection.socket.bufferedAmount + line.length > MAX_QUEUED_BYTES) {
+      abortGeneration(generation, 'bridge_queue_limit');
+      return;
+    }
+    connection.socket.send(line.toString('utf8'), { binary: false });
+  };
+  const handleClientMessage = (connection, data, isBinary) => {
+    if (shuttingDown) return;
+    try {
+      const frame = Buffer.isBuffer(data) ? data : Buffer.from(data);
+      if (isBinary || frame.length > MAX_FRAME_BYTES) throw new Error('bridge_frame_invalid');
+      const parsed = JSON.parse(frame.toString('utf8'));
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error('bridge_message_not_object');
+      const normalizedFrame = Buffer.from(JSON.stringify(parsed), 'utf8');
+      if (!connection.initialized) {
+        const initialize = parseInitialize(normalizedFrame.toString('utf8'));
+        if (
+          connection.isCandidate &&
+          !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) {
+          initializeReceived = true;
+          experimentalApi = initialize.params.capabilities.experimentalApi === true;
+        }
+        if (connection.isCandidate && connection.generation === null) {
+          handoffAttemptCount += 1;
+          connection.generation = spawnMonitor();
+          connection.generation.connection = connection;
+        }
+      }
+      if (parsed.method === 'turn/start') turnStartCount += 1;
+      if (typeof parsed.method === 'string') {
+        if (DIAGNOSTIC_METHODS.has(parsed.method)) {
+          if (observedMethods.size < MAX_DIAGNOSTIC_ENTRIES) observedMethods.add(parsed.method);
+        } else {
+          unknownMethodCount += 1;
         }
-      };
-      webSocket.on('message', (data, isBinary) => {
-        try {
-          const frame = Buffer.isBuffer(data) ? data : Buffer.from(data);
-          if (isBinary || frame.length > MAX_FRAME_BYTES) throw new Error('bridge_frame_invalid');
-          const parsed = JSON.parse(frame.toString('utf8'));
-          if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
-            throw new Error('bridge_message_not_object');
-          const normalizedFrame = Buffer.from(JSON.stringify(parsed), 'utf8');
-          if (!initialized) {
-            const initialize = parseInitialize(normalizedFrame.toString('utf8'));
-            initializeReceived = true;
-            experimentalApi = initialize.params.capabilities.experimentalApi === true;
-            initializeId = initialize.id;
-            initialized = true;
+        if (parsed.method === 'thread/resume') threadResumeCount += 1;
+        if (parsed.method === 'initialize' || parsed.method === 'initialized') {
+          // The notification is part of the handshake and does not affect startup eligibility.
+        } else if (READ_ONLY_DISCOVERY.has(parsed.method)) {
+          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.size < MAX_PENDING_DISCOVERY)
+            connection.pendingRequests.set(parsed.id, parsed.method);
+          else {
+            connection.startedOperation = true;
+            connection.handoffEligible = false;
           }
-          if (parsed.method === 'turn/start') turnStartCount += 1;
+        } else {
+          connection.startedOperation = true;
+          connection.handoffEligible = false;
           if (
-            normalizedFrame.length > MAX_FRAME_BYTES ||
-            queuedFrames >= MAX_QUEUED_FRAMES ||
-            queuedBytes + normalizedFrame.length > MAX_QUEUED_BYTES
+            parsed.method === 'thread/resume' &&
+            ((typeof parsed.id === 'string' && parsed.id.length > 0 && parsed.id.length <= 128) ||
+              (Number.isSafeInteger(parsed.id) && parsed.id >= 0)) &&
+            connection.threadResumeRequestIds.size < MAX_PENDING_DISCOVERY
           )
-            throw new Error('bridge_queue_limit');
-          pendingToMonitor.push(normalizedFrame);
-          queuedFrames += 1;
-          queuedBytes += normalizedFrame.length;
-          flush();
-        } catch (error) {
-          webSocket.close(1008, safeError(error));
-        }
-      });
-      webSocket.on('error', () => void cleanup());
-      monitor.stdin.on('drain', () => {
-        monitorWritable = true;
-        flush();
-      });
-      let monitorBuffer = Buffer.alloc(0);
-      monitor.stdout.on('data', (chunk) => {
-        monitorBuffer = Buffer.concat([monitorBuffer, Buffer.from(chunk)]);
-        while (true) {
-          const newline = monitorBuffer.indexOf(10);
-          if (newline < 0) break;
-          const line = monitorBuffer.subarray(0, newline);
-          monitorBuffer = monitorBuffer.subarray(newline + 1);
-          monitorLineCount += 1;
-          monitorByteCount += line.length + 1;
-          if (line.length === 0) continue;
-          if (line.length > MAX_FRAME_BYTES) {
-            webSocket.close(1013, 'monitor_frame_limit');
-            return;
-          }
-          if (webSocket.readyState !== WebSocket.OPEN) continue;
-          try {
-            const parsed = JSON.parse(line.toString('utf8'));
-            if (initializeId !== null && parsed.id === initializeId) {
-              initializeResponseSeen = true;
-              initializeErrorCode = parsed.error?.code ?? null;
-            }
-            if (typeof parsed.params?.threadId === 'string')
-              observedThreadIds.add(parsed.params.threadId);
-            if (typeof parsed.result?.thread?.id === 'string')
-              observedThreadIds.add(parsed.result.thread.id);
-            if (
-              initializeId !== null &&
-              parsed.id === initializeId &&
-              parsed.error === undefined &&
-              parsed.result !== undefined
-            )
-              initializeAck = true;
-          } catch {
-            // The monitor protocol line is forwarded unchanged; diagnostics stay content-free.
-          }
-          if (webSocket.bufferedAmount + line.length > MAX_QUEUED_BYTES) {
-            webSocket.close(1013, 'bridge_queue_limit');
-            return;
-          }
-          webSocket.send(line.toString('utf8'), { binary: false });
+            connection.threadResumeRequestIds.add(parsed.id);
         }
-        if (monitorBuffer.length > MAX_FRAME_BYTES) webSocket.close(1013, 'monitor_frame_limit');
-      });
-      webSocket.once('close', () => void cleanup().finally(() => process.exit(0)));
+      }
+      if (connection.discoverySatisfied === true && connection.startedOperation === false)
+        connection.handoffEligible = true;
+      if (
+        connection.isCandidate &&
+        connection.initializeAck !== true &&
+        parsed.method !== 'initialize'
+      ) {
+        if (
+          connection.pendingClientFrames.length >= MAX_QUEUED_FRAMES ||
+          connection.pendingClientBytes + normalizedFrame.length > MAX_QUEUED_BYTES
+        )
+          throw new Error('handoff_queue_limit');
+        connection.pendingClientFrames.push(normalizedFrame);
+        connection.pendingClientBytes += normalizedFrame.length;
+      } else {
+        enqueueForMonitor(connection, normalizedFrame);
+      }
+    } catch (error) {
+      if (connection.isCandidate) rejectCandidate(connection, 1008, safeError(error));
+      else connection.socket.close(1008, safeError(error));
+    }
+  };
+  const attachConnection = (webSocket, isCandidate) => {
+    const connection = {
+      socket: webSocket,
+      generation: isCandidate ? null : initialGeneration,
+      isCandidate,
+      isActive: !isCandidate,
+      retiring: false,
+      initialized: false,
+      initializeId: null,
+      initializeAck: false,
+      clientInfo: null,
+      pendingRequests: new Map(),
+      threadResumeRequestIds: new Set(),
+      pendingClientFrames: [],
+      pendingClientBytes: 0,
+      discoverySatisfied: false,
+      handoffEligible: false,
+      startedOperation: false,
+      handoffComplete: false,
+      discoveryClosed: false,
+      candidateTimer: null,
+    };
+    if (!isCandidate) {
+      activeConnection = connection;
+      initialGeneration.connection = connection;
+    }
+    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 {
+        cleanupInitiator = 'socket_error';
+        recordLifecycle('socket_error');
+        clearStartupGrace();
+        void cleanup().finally(() => process.exit(1));
+      }
+    });
+    webSocket.once('close', (code) => {
+      if (connection.retiring || shuttingDown) return;
+      lastSocketCloseCode = code;
+      terminalAliveAtSocketClose = terminal?.exitCode === null;
+      recordLifecycle('socket_close');
+      if (connection.isCandidate) {
+        rejectCandidate(connection);
+        return;
+      }
+      if (
+        pendingCandidate !== null &&
+        connection.handoffEligible === true &&
+        connection.startedOperation === false &&
+        NORMAL_DISCOVERY_CLOSE_CODES.has(code) &&
+        terminal?.exitCode === null
+      ) {
+        connection.discoveryClosed = true;
+        cleanupGeneration(connection.generation);
+        return;
+      }
+      if (pendingCandidate !== null) {
+        cleanupInitiator = 'socket_abnormal_close';
+        cleanupGeneration(connection.generation);
+        failBridge('startup_handoff_failed');
+        return;
+      }
+      if (
+        allowStartupHandoff &&
+        handoffCount === 0 &&
+        handoffAttemptCount === 0 &&
+        connection.initialized === true &&
+        connection.initializeAck === true &&
+        connection.handoffEligible === true &&
+        connection.startedOperation === false &&
+        NORMAL_DISCOVERY_CLOSE_CODES.has(code) &&
+        terminal?.exitCode === null
+      ) {
+        connection.discoveryClosed = true;
+        cleanupGeneration(connection.generation);
+        armStartupGrace(connection);
+        return;
+      }
+      cleanupInitiator = code === 1006 ? 'socket_abnormal_close' : 'socket_close';
+      clearStartupGrace();
+      void cleanup().finally(() => process.exit(0));
+    });
+    return connection;
+  };
+  server.on('upgrade', (request, socket, head) => {
+    socketUpgradeCount += 1;
+    if (shuttingDown) {
+      closeSocket(socket, 503, 'bridge_stopped');
+      return;
+    }
+    if (request.headers.origin !== undefined) {
+      closeSocket(socket, 403, 'origin_rejected');
+      return;
+    }
+    const isCandidate = activeConnection !== null;
+    if (isCandidate && !canHandoff(activeConnection)) {
+      secondConnectionRejectCount += 1;
+      closeSocket(socket, 409, 'second_connection_rejected');
+      return;
+    }
+    webSocketServer.handleUpgrade(request, socket, head, (webSocket) => {
+      const connection = attachConnection(webSocket, isCandidate);
+      if (isCandidate) {
+        pendingCandidate = connection;
+        connection.candidateTimer = setTimeout(
+          () => rejectCandidate(connection, 1008, 'handoff_timeout'),
+          5_000,
+        );
+      }
     });
   });
   try {
@@ -308,8 +749,13 @@ async function main() {
   terminal.on('error', () => void cleanup().finally(() => process.exit(1)));
   terminal.on('exit', (code, signal) => {
     terminalExitCode = code;
-    if (!shuttingDown)
+    terminalExitSignal = signal;
+    recordLifecycle('terminal_exit');
+    clearStartupGrace();
+    if (!shuttingDown) {
+      if (cleanupInitiator === 'unknown') cleanupInitiator = 'terminal_exit';
       void cleanup().finally(() => process.exit(signal === null ? (code ?? 0) : 1));
+    }
   });
 }