create-harness-vibe-coding 0.8.19 → 0.9.3

package/src/wf-ui-server/ws-terminal.mjs

@@ -1,5 +1,4 @@
 import crypto from 'node:crypto';
-import { validateToken } from './token.mjs';
 
 const KEEPALIVE_INTERVAL = 15000;
 const PING_TIMEOUT = 5000;
@@ -11,6 +10,13 @@ const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
 /** @type {Map<string, object>} */
 const ptyRegistry = new Map();
 
+// ── Revived session records ──
+// Sessions revived from disk (backend restarted while the PTY session
+// survived) are keyed here with minimal info so WS clients can reattach
+// even though the in-memory registry does not know them.
+/** @type {Map<string, object>} */
+const revivedSessions = new Map();
+
 /**
  * Register a PTY process for a session so ws-terminal can write/resize/kill it.
  * @param {string} sessionId
@@ -43,6 +49,77 @@ export function killPtyProcess(sessionId) {
   return true;
 }
 
+// ── Graceful stop ──
+// claude-code only persists its conversation transcript on graceful exit
+// (the /exit TUI path writes ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl);
+// a hard PTY kill loses it and --resume <uuid> then fails with "No
+// conversation found". codex persists its fs rollout continuously and
+// opencode writes its SQLite session rows during the session, so a hard kill
+// is safe for both — graceful exit applies to claude/cc ONLY.
+const GRACEFUL_STOP_TIMEOUT_MS = 3000;
+const GRACEFUL_STOP_RUNTIMES = new Set(['claude', 'cc']);
+
+/**
+ * Resolve true when the registered PTY process exits (or when nothing is
+ * attached), false when it is still alive after timeoutMs.
+ * @param {string} sessionId
+ * @param {number} timeoutMs
+ * @returns {Promise<boolean>}
+ */
+function waitForPtyExit(sessionId, timeoutMs) {
+  return new Promise((resolve) => {
+    const ptyProcess = ptyRegistry.get(sessionId);
+    if (!ptyProcess) return resolve(true);
+    if (typeof ptyProcess.onExit !== 'function') return resolve(false);
+    const timer = setTimeout(() => resolve(false), timeoutMs);
+    ptyProcess.onExit(() => {
+      clearTimeout(timer);
+      resolve(true);
+    });
+  });
+}
+
+/**
+ * Stop a PTY process, preferring a graceful runtime exit so the runtime can
+ * persist its session state (claude/cc transcript files).
+ *
+ * claude/cc sequence: write `/exit\r` and wait up to GRACEFUL_STOP_TIMEOUT_MS;
+ * if the process is still alive write Ctrl+C (`\x03`) and wait again; if it
+ * still has not exited, fall back to killPtyProcess. Total wait is bounded
+ * (2 × 3s) so the stop API contract — the process always ends within a
+ * bounded time — is preserved. All other runtimes (codex, opencode, …) go
+ * straight to killPtyProcess.
+ *
+ * Never rejects; the hard-kill fallback guarantees termination.
+ * @param {string} sessionId
+ * @param {{ runtime?: string }} [options]
+ * @returns {Promise<{ killed: boolean, graceful: boolean }>}
+ */
+export function gracefulStopPty(sessionId, { runtime } = {}) {
+  if (!GRACEFUL_STOP_RUNTIMES.has(String(runtime || '').toLowerCase())) {
+    return Promise.resolve({ killed: killPtyProcess(sessionId), graceful: false });
+  }
+  const ptyProcess = ptyRegistry.get(sessionId);
+  if (!ptyProcess || typeof ptyProcess.write !== 'function') {
+    return Promise.resolve({ killed: false, graceful: false });
+  }
+  return (async () => {
+    ptyProcess.write('/exit');
+    ptyProcess.write('\r');
+    let exited = await waitForPtyExit(sessionId, GRACEFUL_STOP_TIMEOUT_MS);
+    if (!exited) {
+      ptyProcess.write('\x03');
+      exited = await waitForPtyExit(sessionId, GRACEFUL_STOP_TIMEOUT_MS);
+    }
+    if (!exited) {
+      killPtyProcess(sessionId);
+      return { killed: true, graceful: false };
+    }
+    unregisterPtyProcess(sessionId);
+    return { killed: false, graceful: true };
+  })();
+}
+
 // ── Frame helpers ──
 
 /**
@@ -162,17 +239,19 @@ function sendHttpError(sock, statusCode, message) {
 /**
  * Attach a WebSocket /ws/terminal/:sessionId endpoint to an existing http.Server.
  *
- * On upgrade: validates `?token=` query param, validates sessionId exists in
- * registry, performs WS upgrade, sends `session:state` handshake, and
+ * On upgrade: validates sessionId exists in registry, performs WS upgrade,
+ * sends `session:state` handshake, and
  * broadcasts PTY data to all WS clients for that session.
  *
  * Default mode is watch (read-only). pty:input is rejected unless
  * session.attachMode === true.
  *
  * @param {import('http').Server} httpServer
- * @param {string} expectedToken - The token clients must present.
+ * @param {string} expectedToken - Compatibility parameter; no token validation is performed.
  * @param {import('./session-registry.mjs').SessionRegistry} sessionRegistry
- * @param {{ keepaliveInterval?: number, pingTimeout?: number }} [options]
+ * @param {{ keepaliveInterval?: number, pingTimeout?: number, reviveSession?: (sessionId: string) => object|null }} [options]
+ *   reviveSession: optional disk lookup for sessions missing from the registry
+ *   (falls back to sessionRegistry.reviveSession when set by the server).
  * @returns {{ close: () => Promise<void>, broadcastToSession: (sessionId: string, msg: object) => void }}
  */
 export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, options = {}) {
@@ -199,13 +278,13 @@ export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, opt
 
     const sessionId = match[1];
 
-    if (!validateToken(url.searchParams.get('token'), expectedToken)) {
-      sendHttpError(socket, 401, 'Invalid or missing token');
-      return;
+    // Validate session exists. Sessions not in the in-memory registry (e.g.
+    // the backend restarted while the PTY session survived on disk) are
+    // revived from the persisted session record so the WS can reattach.
+    let session = sessionRegistry.get(sessionId);
+    if (!session) {
+      session = reviveDiskSession(sessionId);
     }
-
-    // Validate session exists
-    const session = sessionRegistry.get(sessionId);
     if (!session) {
       sendHttpError(socket, 404, `Session "${sessionId}" not found`);
       return;
@@ -237,7 +316,7 @@ export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, opt
     sessionClients.get(sessionId).add(client);
 
     // Increment wsClientCount
-    sessionRegistry.update(sessionId, { wsClientCount: (session.wsClientCount || 0) + 1 });
+    adjustWsClientCount(sessionId, session, 1);
 
     // Send session:state handshake
     sendFrame(socket, JSON.stringify({
@@ -301,7 +380,7 @@ export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, opt
    * @param {import('net').Socket} socket
    */
   function handleMessage(sessionId, msg, socket) {
-    const session = sessionRegistry.get(sessionId);
+    const session = sessionRegistry.get(sessionId) || revivedSessions.get(sessionId);
     if (!session) return;
 
     switch (msg.type) {
@@ -309,7 +388,7 @@ export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, opt
         const cols = typeof msg.cols === 'number' ? msg.cols : session.cols;
         const rows = typeof msg.rows === 'number' ? msg.rows : session.rows;
         if (cols === session.cols && rows === session.rows) break;
-        sessionRegistry.update(sessionId, { cols, rows });
+        storeSessionPatch(sessionId, { cols, rows });
 
         // If a real PTY process exists, resize it
         const ptyProcess = ptyRegistry.get(sessionId);
@@ -353,7 +432,7 @@ export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, opt
 
       case 'control:attach-mode': {
         const attachMode = Boolean(msg.attachMode);
-        sessionRegistry.update(sessionId, { attachMode });
+        storeSessionPatch(sessionId, { attachMode });
         if (typeof options.onAttachModeChange === 'function') {
           options.onAttachModeChange(sessionRegistry.get(sessionId), attachMode);
         }
@@ -374,7 +453,7 @@ export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, opt
           sessionId,
           state: 'exited',
         }));
-        sessionRegistry.update(sessionId, { status: 'exited' });
+        storeSessionPatch(sessionId, { status: 'exited' });
         if (typeof options.onSessionState === 'function') {
           options.onSessionState(sessionRegistry.get(sessionId), 'exited');
         }
@@ -405,10 +484,74 @@ export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, opt
       }
     }
 
-    const session = sessionRegistry.get(sessionId);
+    const session = sessionRegistry.get(sessionId) || revivedSessions.get(sessionId);
     if (session) {
-      const count = Math.max(0, (session.wsClientCount || 1) - 1);
-      sessionRegistry.update(sessionId, { wsClientCount: count });
+      adjustWsClientCount(sessionId, session, -1);
+    }
+  }
+
+  /**
+   * Revive a session that is not in the in-memory registry from its
+   * persisted record (Harness/a2a/sessions/<id>/STATE.json). The PTY process
+   * may still be alive after a backend restart; a WS client can reattach to
+   * watch it (input stays disabled — no live PTY handle). Returns the record
+   * or null when the session is unknown or already exited.
+   * @param {string} sessionId
+   * @returns {object|null}
+   */
+  function reviveDiskSession(sessionId) {
+    const cached = revivedSessions.get(sessionId);
+    if (cached) return cached;
+
+    const revive = (typeof options.reviveSession === 'function' && options.reviveSession)
+      || (typeof sessionRegistry.reviveSession === 'function' && sessionRegistry.reviveSession.bind(sessionRegistry));
+    if (typeof revive !== 'function') return null;
+
+    let record = null;
+    try {
+      record = revive(sessionId);
+    } catch {
+      record = null;
+    }
+    if (!record || !record.sessionId || record.status === 'exited') return null;
+
+    record = { ...record, status: record.status || 'starting' };
+    revivedSessions.set(sessionId, record);
+    return record;
+  }
+
+  /**
+   * Apply a patch to a session record, preferring the in-memory registry and
+   * falling back to a revived disk record.
+   * @param {string} sessionId
+   * @param {object} patch
+   */
+  function storeSessionPatch(sessionId, patch) {
+    if (sessionRegistry.get(sessionId)) {
+      sessionRegistry.update(sessionId, patch);
+      return;
+    }
+    const current = revivedSessions.get(sessionId);
+    if (current) {
+      revivedSessions.set(sessionId, { ...current, ...patch, updatedAt: new Date().toISOString() });
+    }
+  }
+
+  /**
+   * Adjust wsClientCount by delta in whichever store owns the session.
+   * @param {string} sessionId
+   * @param {object} session
+   * @param {number} delta
+   */
+  function adjustWsClientCount(sessionId, session, delta) {
+    const next = Math.max(0, (session?.wsClientCount || 0) + delta);
+    if (sessionRegistry.get(sessionId)) {
+      sessionRegistry.update(sessionId, { wsClientCount: next });
+      return;
+    }
+    const current = revivedSessions.get(sessionId);
+    if (current) {
+      revivedSessions.set(sessionId, { ...current, wsClientCount: next });
     }
   }
 
@@ -434,14 +577,14 @@ export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, opt
   // ── keepalive timer ──
   keepaliveTimer = setInterval(() => {
     const now = Date.now();
-    for (const [, clients] of sessionClients) {
+    for (const [sessionId, clients] of sessionClients) {
       for (const c of [...clients]) {
         try {
           if (c.waitingPong) {
             if (now - c.pingSentAt >= pingTimeoutMs) {
               sendCloseFrame(c.socket, 1001);
               c.socket.end();
-              clients.delete(c);
+              cleanupClient(sessionId, c);
             }
           } else if (now - c.lastActivity >= keepaliveInterval) {
             sendFrame(c.socket, '', 0x9);
@@ -449,7 +592,7 @@ export function attachTerminalWs(httpServer, expectedToken, sessionRegistry, opt
             c.pingSentAt = now;
           }
         } catch {
-          clients.delete(c);
+          cleanupClient(sessionId, c);
         }
       }
     }

package/src/wf-ui-server/ws-wf-browser.mjs

@@ -0,0 +1,419 @@
+import crypto from 'node:crypto';
+
+const KEEPALIVE_INTERVAL = 15000;
+const PING_TIMEOUT = 5000;
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
+const MAX_COMMAND_TIMEOUT_MS = 30000;
+const DEFAULT_MAX_MESSAGE_BYTES = 1024 * 1024;
+
+export class WfBrowserWsError extends Error {
+  constructor(message, { statusCode = 400, code = 'BAD_REQUEST' } = {}) {
+    super(message);
+    this.name = 'WfBrowserWsError';
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+}
+
+function sendFrame(socket, text, opcode = 0x1) {
+  const data = Buffer.from(text, 'utf8');
+  const len = data.length;
+  let frame;
+  if (len < 126) {
+    frame = Buffer.alloc(2 + len);
+    frame[0] = 0x80 | opcode;
+    frame[1] = len;
+    data.copy(frame, 2);
+  } else if (len < 65536) {
+    frame = Buffer.alloc(4 + len);
+    frame[0] = 0x80 | opcode;
+    frame[1] = 126;
+    frame.writeUInt16BE(len, 2);
+    data.copy(frame, 4);
+  } else {
+    frame = Buffer.alloc(10 + len);
+    frame[0] = 0x80 | opcode;
+    frame[1] = 127;
+    frame.writeBigUInt64BE(BigInt(len), 2);
+    data.copy(frame, 10);
+  }
+  socket.write(frame);
+}
+
+function sendJsonFrame(socket, payload) {
+  sendFrame(socket, JSON.stringify(payload));
+}
+
+function sendCloseFrame(socket, code = 1000) {
+  const payload = Buffer.alloc(2);
+  payload.writeUInt16BE(code, 0);
+  const header = Buffer.alloc(2);
+  header[0] = 0x88;
+  header[1] = 2;
+  socket.write(Buffer.concat([header, payload]));
+}
+
+function parseFrames(buffer) {
+  const frames = [];
+  let offset = 0;
+  while (offset + 2 <= buffer.length) {
+    const b1 = buffer[offset];
+    const opcode = b1 & 0x0F;
+    const b2 = buffer[offset + 1];
+    const masked = (b2 & 0x80) !== 0;
+    let payloadLen = b2 & 0x7F;
+    let headerLen = 2;
+    if (payloadLen === 126) {
+      if (offset + 4 > buffer.length) break;
+      payloadLen = buffer.readUInt16BE(offset + 2);
+      headerLen = 4;
+    } else if (payloadLen === 127) {
+      if (offset + 10 > buffer.length) break;
+      payloadLen = Number(buffer.readBigUInt64BE(offset + 2));
+      headerLen = 10;
+    }
+    const maskLen = masked ? 4 : 0;
+    if (offset + headerLen + maskLen + payloadLen > buffer.length) break;
+    offset += headerLen;
+    let payload;
+    if (masked) {
+      const mask = buffer.slice(offset, offset + 4);
+      offset += 4;
+      payload = Buffer.allocUnsafe(payloadLen);
+      for (let i = 0; i < payloadLen; i += 1) {
+        payload[i] = buffer[offset + i] ^ mask[i % 4];
+      }
+    } else {
+      payload = buffer.slice(offset, offset + payloadLen);
+    }
+    offset += payloadLen;
+    frames.push({ opcode, payload });
+  }
+  return { frames, remainder: buffer.slice(offset) };
+}
+
+function sendHttpError(sock, statusCode, message) {
+  let code;
+  if (statusCode === 401) code = 'UNAUTHORIZED';
+  else if (statusCode === 404) code = 'NOT_FOUND';
+  else code = 'ERROR';
+  const body = JSON.stringify({ error: { code, message } });
+  const reason = statusCode === 401 ? 'Unauthorized' : statusCode === 404 ? 'Not Found' : 'Error';
+  sock.write(
+    `HTTP/1.1 ${statusCode} ${reason}\r\n` +
+    'Content-Type: application/json\r\n' +
+    `Content-Length: ${body.length}\r\n` +
+    'Connection: close\r\n\r\n' + body
+  );
+  sock.end();
+}
+
+function connectionKey(runId, windowId) {
+  return `${runId || ''}:${windowId || ''}`;
+}
+
+function cleanString(value, fallback = '') {
+  const text = String(value || '').trim();
+  return text || fallback;
+}
+
+function normalizeCommand(payload = {}) {
+  const command = payload.command && typeof payload.command === 'object' ? payload.command : {};
+  const commandId = cleanString(payload.commandId || command.commandId, `command-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`);
+  const primitive = cleanString(payload.primitive || command.primitive, '');
+  if (!primitive) {
+    throw new WfBrowserWsError('wf-browser command requires a primitive');
+  }
+  return {
+    commandId,
+    primitive,
+    agentId: cleanString(payload.agentId || command.agentId, ''),
+    sessionId: cleanString(payload.sessionId || command.sessionId, ''),
+    runId: cleanString(payload.runId || command.runId, ''),
+    windowId: cleanString(payload.windowId || command.windowId, ''),
+    leaseId: cleanString(payload.leaseId || command.leaseId, ''),
+    payload: payload.payload ?? command.payload ?? {},
+    timeoutMs: Math.min(Math.max(Number(payload.timeoutMs || command.timeoutMs || DEFAULT_COMMAND_TIMEOUT_MS), 500), MAX_COMMAND_TIMEOUT_MS),
+  };
+}
+
+export function attachWfBrowserWs(httpServer, expectedToken, projectRoot, options = {}) {
+  const keepaliveInterval = options.keepaliveInterval || KEEPALIVE_INTERVAL;
+  const pingTimeoutMs = options.pingTimeout || PING_TIMEOUT;
+  const tickMs = Math.min(keepaliveInterval, pingTimeoutMs) / 2;
+  const maxMessageBytes = options.maxMessageBytes || DEFAULT_MAX_MESSAGE_BYTES;
+  const clients = new Set();
+  const frontendByWindow = new Map();
+  const pendingCommands = new Map();
+  let keepaliveTimer = null;
+
+  httpServer.on('upgrade', (req, socket, head) => {
+    const url = new URL(req.url, `http://${req.headers.host || '127.0.0.1'}`);
+    if (url.pathname !== '/ws/wf-browser') return;
+
+    const key = req.headers['sec-websocket-key'];
+    const digest = crypto.createHash('sha1').update(key + WS_GUID).digest('base64');
+    socket.write(
+      'HTTP/1.1 101 Switching Protocols\r\n' +
+      'Upgrade: websocket\r\n' +
+      'Connection: Upgrade\r\n' +
+      'Sec-WebSocket-Accept: ' + digest + '\r\n\r\n'
+    );
+
+    const connectionId = crypto.randomBytes(16).toString('hex');
+    const client = {
+      socket,
+      connectionId,
+      role: 'unknown',
+      runId: '',
+      windowId: '',
+      agentId: '',
+      route: '',
+      capabilities: [],
+      connectedAt: new Date().toISOString(),
+      lastActivity: Date.now(),
+      waitingPong: false,
+      pingSentAt: 0,
+    };
+    clients.add(client);
+
+    sendJsonFrame(socket, {
+      type: 'wf-browser.connected',
+      protocolVersion: 1,
+      connectionId,
+      projectRoot,
+      maxMessageBytes,
+      ts: new Date().toISOString(),
+    });
+
+    let buffer = Buffer.alloc(0);
+    if (head && head.length > 0) buffer = Buffer.concat([buffer, head]);
+
+    socket.on('data', (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      client.lastActivity = Date.now();
+      const result = parseFrames(buffer);
+      buffer = result.remainder;
+      for (const frame of result.frames) {
+        if (frame.payload.length > maxMessageBytes) {
+          sendCloseFrame(socket, 1009);
+          cleanupClient(client);
+          socket.end();
+          return;
+        }
+        if (frame.opcode === 0x9) {
+          sendFrame(socket, '', 0xA);
+        } else if (frame.opcode === 0xA) {
+          client.waitingPong = false;
+        } else if (frame.opcode === 0x8) {
+          sendCloseFrame(socket, 1000);
+          cleanupClient(client);
+          socket.end();
+          return;
+        } else if (frame.opcode === 0x1) {
+          try {
+            handleMessage(client, JSON.parse(frame.payload.toString('utf8')));
+          } catch (err) {
+            sendJsonFrame(socket, {
+              type: 'error',
+              code: err?.code || 'BAD_MESSAGE',
+              message: err?.message || 'Malformed wf-browser message',
+            });
+          }
+        }
+      }
+    });
+
+    socket.on('close', () => cleanupClient(client));
+    socket.on('end', () => cleanupClient(client));
+    socket.on('error', () => cleanupClient(client));
+  });
+
+  function handleMessage(client, msg) {
+    if (!msg || typeof msg !== 'object') return;
+    if (msg.type === 'hello') {
+      registerClient(client, msg);
+      return;
+    }
+    if (msg.type === 'heartbeat') {
+      sendJsonFrame(client.socket, {
+        type: 'heartbeat.ack',
+        connectionId: client.connectionId,
+        ts: new Date().toISOString(),
+      });
+      return;
+    }
+    if (msg.type === 'ack') {
+      const pending = pendingCommands.get(msg.commandId);
+      if (pending) pending.ack = { ...msg, receivedAt: new Date().toISOString() };
+      return;
+    }
+    if (msg.type === 'result') {
+      const pending = pendingCommands.get(msg.commandId);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      pendingCommands.delete(msg.commandId);
+      pending.resolve({
+        commandId: msg.commandId,
+        status: msg.status || 'ok',
+        result: msg.result ?? null,
+        artifacts: Array.isArray(msg.artifacts) ? msg.artifacts : [],
+        events: Array.isArray(msg.events) ? msg.events : [],
+        error: msg.error || null,
+        ack: pending.ack || null,
+        receivedAt: new Date().toISOString(),
+      });
+    }
+  }
+
+  function registerClient(client, msg) {
+    const previousKey = client.runId && client.windowId ? connectionKey(client.runId, client.windowId) : '';
+    if (previousKey && frontendByWindow.get(previousKey) === client) frontendByWindow.delete(previousKey);
+    client.role = cleanString(msg.role, 'frontend');
+    client.runId = cleanString(msg.runId, '');
+    client.windowId = cleanString(msg.windowId, '');
+    client.agentId = cleanString(msg.agentId, '');
+    client.route = cleanString(msg.route?.pathname || msg.route, '');
+    client.capabilities = Array.isArray(msg.capabilities) ? msg.capabilities.slice(0, 500) : [];
+    if (client.role === 'frontend' && client.runId && client.windowId) {
+      frontendByWindow.set(connectionKey(client.runId, client.windowId), client);
+    }
+    sendJsonFrame(client.socket, {
+      type: 'hello.ack',
+      status: 'registered',
+      connectionId: client.connectionId,
+      role: client.role,
+      runId: client.runId,
+      windowId: client.windowId,
+      capabilityCount: client.capabilities.length,
+      ts: new Date().toISOString(),
+    });
+  }
+
+  function cleanupClient(client) {
+    if (client._cleanedUp) return;
+    client._cleanedUp = true;
+    clients.delete(client);
+    const key = client.runId && client.windowId ? connectionKey(client.runId, client.windowId) : '';
+    if (key && frontendByWindow.get(key) === client) frontendByWindow.delete(key);
+    for (const [commandId, pending] of [...pendingCommands.entries()]) {
+      if (pending.client === client) {
+        clearTimeout(pending.timer);
+        pendingCommands.delete(commandId);
+        pending.reject(new WfBrowserWsError('wf-browser frontend disconnected before command completed', {
+          statusCode: 409,
+          code: 'WINDOW_DISCONNECTED',
+        }));
+      }
+    }
+  }
+
+  function sendCommand(payload = {}) {
+    const command = normalizeCommand(payload);
+    const client = frontendByWindow.get(connectionKey(command.runId, command.windowId));
+    if (!client || client.socket.destroyed) {
+      throw new WfBrowserWsError(`wf-browser window is not connected: ${command.windowId}`, {
+        statusCode: 409,
+        code: 'WINDOW_NOT_CONNECTED',
+      });
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingCommands.delete(command.commandId);
+        reject(new WfBrowserWsError(`wf-browser command timed out: ${command.commandId}`, {
+          statusCode: 504,
+          code: 'COMMAND_TIMEOUT',
+        }));
+      }, command.timeoutMs);
+      pendingCommands.set(command.commandId, {
+        client,
+        command,
+        resolve,
+        reject,
+        timer,
+        ack: null,
+      });
+      try {
+        sendJsonFrame(client.socket, {
+          type: 'command',
+          protocolVersion: 1,
+          commandId: command.commandId,
+          primitive: command.primitive,
+          runId: command.runId,
+          windowId: command.windowId,
+          leaseId: command.leaseId,
+          agentId: command.agentId,
+          sessionId: command.sessionId,
+          payload: command.payload,
+          ts: new Date().toISOString(),
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        pendingCommands.delete(command.commandId);
+        reject(err);
+      }
+    });
+  }
+
+  function listConnections() {
+    return [...clients].map(client => ({
+      connectionId: client.connectionId,
+      role: client.role,
+      runId: client.runId,
+      windowId: client.windowId,
+      agentId: client.agentId,
+      route: client.route,
+      capabilityCount: client.capabilities.length,
+      connectedAt: client.connectedAt,
+      lastActivityAt: new Date(client.lastActivity).toISOString(),
+    }));
+  }
+
+  keepaliveTimer = setInterval(() => {
+    const now = Date.now();
+    for (const client of [...clients]) {
+      try {
+        if (client.waitingPong) {
+          if (now - client.pingSentAt >= pingTimeoutMs) {
+            sendCloseFrame(client.socket, 1001);
+            client.socket.end();
+            cleanupClient(client);
+          }
+        } else if (now - client.lastActivity >= keepaliveInterval) {
+          sendFrame(client.socket, '', 0x9);
+          client.waitingPong = true;
+          client.pingSentAt = now;
+        }
+      } catch {
+        cleanupClient(client);
+      }
+    }
+  }, Math.max(tickMs, 100));
+
+  function close() {
+    return new Promise((resolve) => {
+      if (keepaliveTimer) clearInterval(keepaliveTimer);
+      for (const client of [...clients]) {
+        try { sendCloseFrame(client.socket, 1001); client.socket.end(); } catch { /* ignore */ }
+      }
+      clients.clear();
+      frontendByWindow.clear();
+      for (const [, pending] of pendingCommands) {
+        clearTimeout(pending.timer);
+        pending.reject(new WfBrowserWsError('wf-browser bridge closed', {
+          statusCode: 409,
+          code: 'BRIDGE_CLOSED',
+        }));
+      }
+      pendingCommands.clear();
+      resolve();
+    });
+  }
+
+  return {
+    close,
+    sendCommand,
+    listConnections,
+  };
+}