@dmsdc-ai/aigentry-telepty 0.5.1 → 0.5.3

package/src/transport/websocket.js

@@ -0,0 +1,295 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { WebSocketServer } = require('ws');
+
+function isOpenWebSocket(ws) {
+  return Boolean(ws && ws.readyState === 1);
+}
+
+function installWebSocketTransport(deps) {
+  const {
+    server,
+    sessions,
+    busClients,
+    expectedToken,
+    verifyJwt,
+    isAllowedPeer,
+    initializeBootstrapState,
+    findKittySocket,
+    findKittyWindowId,
+    markSessionConnected,
+    scheduleBootstrapPromptPoll,
+    emitSessionLifecycleEvent,
+    persistSessions,
+    appendToOutputRing,
+    sessionStateManager,
+    isBootstrapGatedSession,
+    markBootstrapReady,
+    pendingReports,
+    fireAutoReport,
+    markSessionDisconnected,
+    resolveSessionAlias,
+    applySessionStateReport,
+    relayToPeers,
+    busAutoRoute
+  } = deps;
+
+  const wss = new WebSocketServer({ noServer: true });
+
+  wss.on('connection', (ws, req) => {
+    const url = new URL(req.url, 'http://' + req.headers.host);
+    const sessionId = url.pathname.split('/').pop();
+    const session = sessions[sessionId];
+    // ?owner=1 indicates the allow bridge (PTY owner), not an attach viewer
+    const isOwnerConnect = url.searchParams.get('owner') === '1';
+
+    // Ping/pong heartbeat — detect and terminate stale TCP half-open connections (30s interval)
+    let isAlive = true;
+    ws.on('pong', () => { isAlive = true; });
+    const pingInterval = setInterval(() => {
+      if (!isAlive) {
+        console.log(`[WS] Terminating stale connection (no pong) for ${sessionId}`);
+        ws.terminate();
+        return;
+      }
+      isAlive = false;
+      ws.ping();
+    }, 30000);
+
+    if (!session) {
+      const connectedAt = new Date().toISOString();
+      // Auto-register wrapped session on WS connect (supports reconnect after daemon restart)
+      const autoSession = {
+        id: sessionId,
+        type: 'wrapped',
+        ptyProcess: null,
+        ownerWs: ws,
+        command: 'wrapped',
+        cwd: process.cwd(),
+        createdAt: connectedAt,
+        lastActivityAt: connectedAt,
+        lastConnectedAt: connectedAt,
+        lastDisconnectedAt: null,
+        clients: new Set([ws]),
+        isClosing: false,
+        outputRing: [],
+        ready: true,
+            };
+      initializeBootstrapState(autoSession);
+      sessions[sessionId] = autoSession;
+      console.log(`[WS] Auto-registered wrapped session ${sessionId} on reconnect`);
+      // Set tab title via kitty (no \x0c redraw — it causes flickering on multi-session reconnect)
+      setTimeout(() => {
+        const sock = findKittySocket();
+        const wid = findKittyWindowId(sock, sessionId);
+        if (sock && wid) {
+          try {
+            require('child_process').execSync(`kitty @ --to unix:${sock} set-tab-title --match id:${wid} '⚡ telepty :: ${sessionId}'`, {
+              timeout: 2000, stdio: ['pipe', 'pipe', 'pipe']
+            });
+          } catch {}
+        }
+      }, 1000);
+    } else {
+      session.clients.add(ws);
+    }
+
+    const activeSession = sessions[sessionId];
+
+    // For wrapped sessions, first connector OR explicit ?owner=1 claim becomes the owner.
+    // ?owner=1 reclaim handles the stale-ownerWs bug: allow bridge reconnects but stale TCP
+    // half-open connection still holds ownerWs slot → reconnect wrongly becomes a viewer.
+    if (activeSession.type === 'wrapped' && (!activeSession.ownerWs || isOwnerConnect)) {
+      const hadDisconnectedOwner = !isOpenWebSocket(activeSession.ownerWs) && activeSession.lastDisconnectedAt;
+      if (isOwnerConnect && activeSession.ownerWs && activeSession.ownerWs !== ws) {
+        // Terminate the stale owner connection before claiming ownership
+        console.log(`[WS] Replacing stale ownerWs for session ${sessionId}`);
+        activeSession.ownerWs.terminate();
+      }
+      activeSession.ownerWs = ws;
+      // BUG-C: mint a fresh per-owner token on every claim/reclaim and push it to this owner.
+      // The token is the exact "are-you-the-current-owner" discriminator the DELETE guard uses
+      // to suppress a stale/displaced owner's teardown (shared-fate fix). Reclaim refreshes it,
+      // so the live current owner always holds the current token while a displaced owner keeps a
+      // stale one.
+      activeSession.ownerToken = crypto.randomUUID();
+      try { ws.send(JSON.stringify({ type: 'owner_token', token: activeSession.ownerToken })); } catch {}
+      markSessionConnected(activeSession);
+      initializeBootstrapState(activeSession);
+      console.log(`[WS] Wrap owner ${isOwnerConnect && activeSession.clients.size > 1 ? 're-' : ''}connected for session ${sessionId} (Total: ${activeSession.clients.size})`);
+      scheduleBootstrapPromptPoll(sessionId, activeSession);
+      if (hadDisconnectedOwner) {
+        emitSessionLifecycleEvent('session_reconnect', sessionId, activeSession);
+      }
+      persistSessions();
+    } else {
+      console.log(`[WS] Client attached to session ${sessionId} (Total: ${activeSession.clients.size})`);
+    }
+
+    ws.on('message', (message) => {
+      try {
+        const { type, data, cols, rows } = JSON.parse(message);
+
+        if (activeSession.type === 'wrapped') {
+          if (ws === activeSession.ownerWs) {
+            // Owner sending output -> broadcast to other clients + update activity
+            if (type === 'output') {
+              activeSession.lastActivityAt = new Date().toISOString();
+              appendToOutputRing(activeSession, data);
+              sessionStateManager.feed(sessionId, data);
+              activeSession.clients.forEach(client => {
+                if (client !== ws && client.readyState === 1) {
+                  client.send(JSON.stringify({ type: 'output', data }));
+                }
+              });
+            } else if (type === 'ready') {
+              if (isBootstrapGatedSession(activeSession)) {
+                markBootstrapReady(sessionId, activeSession, 'bridge_ready');
+              } else {
+                activeSession.ready = true;
+              }
+              activeSession.lastActivityAt = new Date().toISOString();
+              console.log(`[READY] Session ${sessionId} CLI is ready for inject`);
+              // Broadcast readiness to bus (cmux/kitty paths now enabled for this session)
+              const readyMsg = JSON.stringify({
+                type: 'session_ready',
+                session_id: sessionId,
+                timestamp: new Date().toISOString()
+              });
+              busClients.forEach(client => {
+                if (client.readyState === 1) client.send(readyMsg);
+              });
+              // Auto-report: notify source that target completed inject task
+              // Legacy ready-signal auto-report path. Skip if onTransition already
+              // fired (pendingReports[sessionId].idleNotified === true).
+              const pendingReport = pendingReports[sessionId];
+              if (pendingReport && !pendingReport.idleNotified) {
+                // ready-signal: cli.js bridge emitted a 'ready' WS frame.
+                fireAutoReport(sessionId, activeSession, pendingReport, 'ready-signal');
+              }
+            }
+          } else {
+            // Non-owner client input -> forward to owner as inject
+            if (type === 'input' && activeSession.ownerWs && activeSession.ownerWs.readyState === 1) {
+              activeSession.ownerWs.send(JSON.stringify({ type: 'inject', data }));
+            } else if (type === 'resize' && activeSession.ownerWs && activeSession.ownerWs.readyState === 1) {
+              activeSession.ownerWs.send(JSON.stringify({ type: 'resize', cols, rows }));
+            }
+          }
+        } else {
+          // Existing spawned session logic
+          if (type === 'input') {
+            activeSession.ptyProcess.write(data);
+          } else if (type === 'resize') {
+            activeSession.ptyProcess.resize(cols, rows);
+          }
+        }
+      } catch (e) {
+        console.error('[WS] Invalid message format', e);
+      }
+    });
+
+    ws.on('close', () => {
+      clearInterval(pingInterval);
+      activeSession.clients.delete(ws);
+      if (activeSession.type === 'wrapped' && ws === activeSession.ownerWs) {
+        activeSession.ownerWs = null;
+        // #29: cancel any pending owner-alive optimistic timer — the owner is gone, so the
+        // floor must not flip a disconnected session ready (hygiene; the timer also re-guards
+        // on isOpenWebSocket, but clearing avoids a dangling handle).
+        if (activeSession.bootstrapOptimisticTimer) {
+          clearTimeout(activeSession.bootstrapOptimisticTimer);
+          activeSession.bootstrapOptimisticTimer = null;
+        }
+        markSessionDisconnected(activeSession);
+        console.log(`[WS] Wrap owner disconnected from session ${sessionId} (Total: ${activeSession.clients.size})`);
+        emitSessionLifecycleEvent('session_disconnect', sessionId, activeSession, {
+          clients: activeSession.clients.size
+        });
+        persistSessions();
+      } else {
+        console.log(`[WS] Client detached from session ${sessionId} (Total: ${activeSession.clients.size})`);
+      }
+    });
+  });
+
+  const busWss = new WebSocketServer({ noServer: true });
+
+  busWss.on('connection', (ws, req) => {
+    busClients.add(ws);
+    console.log('[BUS] New agent connected to event bus');
+
+    ws.on('message', (message) => {
+      try {
+        const msg = JSON.parse(message);
+        if (msg.type === 'session_state_report') {
+          const resolvedId = resolveSessionAlias(msg.session_id || '');
+          if (!resolvedId || !sessions[resolvedId]) {
+            return;
+          }
+
+          const applied = applySessionStateReport(resolvedId, sessions[resolvedId], msg);
+          if (!applied.success) {
+            return;
+          }
+
+          if (!msg._relayed_from) relayToPeers(applied.event);
+          persistSessions();
+          return;
+        }
+
+        // Broadcast to all other bus clients
+        busClients.forEach(client => {
+          if (client !== ws && client.readyState === 1) {
+            client.send(JSON.stringify(msg));
+          }
+        });
+
+        // Auto-route turn_request events (shared logic with HTTP publish)
+        busAutoRoute(msg);
+        // Relay to peer daemons (dedup prevents loops)
+        if (!msg._relayed_from) relayToPeers(msg);
+      } catch (e) {
+        console.error('[BUS] Invalid message format', e);
+      }
+    });
+
+    ws.on('close', () => {
+      busClients.delete(ws);
+      console.log('[BUS] Agent disconnected from event bus');
+    });
+  });
+
+  if (server) server.on('upgrade', (req, socket, head) => {
+    const url = new URL(req.url, 'http://' + req.headers.host);
+    const token = url.searchParams.get('token');
+
+    const wsAuthHeader = req.headers['authorization'] || '';
+    const wsJwtValid = wsAuthHeader.startsWith('Bearer ') && verifyJwt(wsAuthHeader.slice(7));
+    if (!isAllowedPeer(req.socket.remoteAddress) && token !== expectedToken && !wsJwtValid) {
+      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+
+    if (url.pathname.startsWith('/api/sessions/')) {
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        wss.emit('connection', ws, req);
+      });
+    } else if (url.pathname === '/api/bus') {
+      busWss.handleUpgrade(req, socket, head, (ws) => {
+        busWss.emit('connection', ws, req);
+      });
+    } else {
+      socket.destroy();
+    }
+  });
+
+  return { wss, busWss };
+}
+
+module.exports = {
+  installWebSocketTransport,
+  isOpenWebSocket
+};

package/terminal-backend.js

@@ -168,6 +168,344 @@ function isSurfaceAlive(session) {
   return present ? 'alive' : 'gone';
 }
 
+function getExpectedPtyPid(session) {
+  if (!session) return null;
+  const candidates = [
+    session.ptyPid,
+    session.pty_pid,
+    session.ptyProcess && session.ptyProcess.pid,
+    session.pid
+  ];
+  for (const pid of candidates) {
+    const n = Number(pid);
+    if (Number.isInteger(n) && n > 0) return n;
+  }
+  return null;
+}
+
+function isPtyPidAlive(pid, options = {}) {
+  const processKill = options.processKill || process.kill;
+  try {
+    processKill(pid, 0);
+    return true;
+  } catch (err) {
+    return !!(err && err.code === 'EPERM');
+  }
+}
+
+function normalizeTty(value) {
+  if (typeof value !== 'string') return null;
+  const tty = value.trim().replace(/^\/dev\//, '');
+  if (!tty || tty === '?' || tty === '??') return null;
+  return tty.toLowerCase();
+}
+
+function readProcessTty(pid, options = {}) {
+  if (typeof options.readProcessTty === 'function') {
+    return normalizeTty(options.readProcessTty(pid));
+  }
+  const execFile = options.execFileSync || execFileSync;
+  try {
+    return normalizeTty(execFile('ps', ['-o', 'tty=', '-p', String(pid)], {
+      timeout: 2000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }));
+  } catch {
+    return null;
+  }
+}
+
+function asString(value) {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number') return String(value);
+  return null;
+}
+
+function getObjectString(obj, keys) {
+  if (!obj || typeof obj !== 'object') return null;
+  for (const key of keys) {
+    const value = asString(obj[key]);
+    if (value) return value;
+  }
+  return null;
+}
+
+function lower(value) {
+  return String(value || '').toLowerCase();
+}
+
+function stringMatchesRef(value, ref) {
+  if (!value || !ref) return false;
+  return lower(value) === lower(ref);
+}
+
+function collectObjects(value, out = []) {
+  if (!value || typeof value !== 'object') return out;
+  if (Array.isArray(value)) {
+    for (const item of value) collectObjects(item, out);
+    return out;
+  }
+  out.push(value);
+  for (const child of Object.values(value)) collectObjects(child, out);
+  return out;
+}
+
+const WORKSPACE_REF_KEYS = [
+  'workspaceId', 'workspace_id', 'workspaceRef', 'workspace_ref',
+  'id', 'ref', 'uuid'
+];
+const SURFACE_REF_KEYS = [
+  'surfaceId', 'surface_id', 'surfaceRef', 'surface_ref',
+  'terminalSurfaceId', 'terminal_surface_id',
+  'terminalSurfaceRef', 'terminal_surface_ref',
+  'id', 'ref', 'uuid'
+];
+const TITLE_KEYS = ['title', 'name', 'label', 'tabTitle', 'tab_title'];
+
+function objectType(obj) {
+  return lower(getObjectString(obj, ['type', 'kind', 'nodeType', 'node_type']));
+}
+
+function getWorkspaceRef(obj) {
+  if (!obj || typeof obj !== 'object') return null;
+  for (const key of WORKSPACE_REF_KEYS) {
+    const value = asString(obj[key]);
+    if (!value) continue;
+    if (key.toLowerCase().includes('workspace') || lower(value).startsWith('workspace:') || objectType(obj).includes('workspace')) {
+      return value;
+    }
+  }
+  return null;
+}
+
+function getSurfaceRef(obj) {
+  if (!obj || typeof obj !== 'object') return null;
+  for (const key of SURFACE_REF_KEYS) {
+    const value = asString(obj[key]);
+    if (!value) continue;
+    if (key.toLowerCase().includes('surface') || lower(value).startsWith('surface:') || objectType(obj).includes('surface')) {
+      return value;
+    }
+  }
+  return null;
+}
+
+function getTitle(obj) {
+  return getObjectString(obj, TITLE_KEYS);
+}
+
+function titleHasSessionMarker(title, sessionId) {
+  if (!title || !sessionId) return false;
+  const marker = `telepty :: ${sessionId}`;
+  return title === sessionId || title.includes(marker);
+}
+
+function isWorkspaceCandidate(obj) {
+  return objectType(obj).includes('workspace') || lower(getWorkspaceRef(obj)).startsWith('workspace:');
+}
+
+function isSurfaceCandidate(obj) {
+  return objectType(obj).includes('surface') || lower(getSurfaceRef(obj)).startsWith('surface:');
+}
+
+function workspaceMatches(obj, session, sessionId) {
+  const wid = session.cmuxWorkspaceId;
+  if (wid) {
+    for (const key of WORKSPACE_REF_KEYS) {
+      if (stringMatchesRef(asString(obj[key]), wid)) return true;
+    }
+  }
+  const title = getTitle(obj);
+  return title === sessionId || title === `telepty :: ${sessionId}`;
+}
+
+function findWorkspace(tree, session, sessionId) {
+  const matches = collectObjects(tree).filter((obj) => workspaceMatches(obj, session, sessionId));
+  if (matches.length === 0) return null;
+  return matches.find(isWorkspaceCandidate) || matches[0];
+}
+
+function isSelectedSurface(obj, selectedRef) {
+  if (!obj || typeof obj !== 'object') return false;
+  if (selectedRef && stringMatchesRef(getSurfaceRef(obj), selectedRef)) return true;
+  if (obj.selected === true || obj.active === true || obj.focused === true || obj.isSelected === true) return true;
+  const status = lower(getObjectString(obj, ['status', 'state']));
+  if (status.includes('selected') || status.includes('active') || status.includes('focused')) return true;
+  const title = getTitle(obj);
+  return !!(title && title.includes('[selected]'));
+}
+
+function getSelectedSurfaceRef(workspace) {
+  if (!workspace || typeof workspace !== 'object') return null;
+  const selectedKeys = [
+    'selectedSurface', 'selected_surface',
+    'selectedSurfaceRef', 'selected_surface_ref',
+    'activeSurface', 'active_surface',
+    'activeSurfaceRef', 'active_surface_ref',
+    'focusedSurface', 'focused_surface',
+    'focusedSurfaceRef', 'focused_surface_ref',
+    'terminalSurface', 'terminal_surface'
+  ];
+  for (const key of selectedKeys) {
+    const value = workspace[key];
+    if (value && typeof value === 'object') return getSurfaceRef(value);
+    const stringValue = asString(value);
+    if (stringValue) return stringValue;
+  }
+  return null;
+}
+
+function getSelectedSurfaceObject(workspace) {
+  if (!workspace || typeof workspace !== 'object') return null;
+  const selectedKeys = [
+    'selectedSurface', 'selected_surface',
+    'activeSurface', 'active_surface',
+    'focusedSurface', 'focused_surface',
+    'terminalSurface', 'terminal_surface'
+  ];
+  for (const key of selectedKeys) {
+    const value = workspace[key];
+    if (value && typeof value === 'object') return value;
+  }
+  return null;
+}
+
+function findSelectedSurface(workspace) {
+  if (!workspace || typeof workspace !== 'object') return null;
+  const direct = getSelectedSurfaceObject(workspace);
+  if (direct) return direct;
+  if (isSurfaceCandidate(workspace) && isSelectedSurface(workspace)) return workspace;
+  const selectedRef = getSelectedSurfaceRef(workspace);
+  const surfaces = collectObjects(workspace).filter(isSurfaceCandidate);
+  const selected = surfaces.find((surface) => isSelectedSurface(surface, selectedRef));
+  if (selected) return selected;
+  if (selectedRef) return { ref: selectedRef };
+  return surfaces.length === 1 ? surfaces[0] : null;
+}
+
+function findTtyValue(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const tty = findTtyValue(item);
+      if (tty) return tty;
+    }
+    return null;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (key.toLowerCase().includes('tty')) {
+      const tty = normalizeTty(asString(child));
+      if (tty) return tty;
+    }
+    if (child && typeof child === 'object') {
+      const nested = findTtyValue(child);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+function formatObservedSurface(surface) {
+  const ref = getSurfaceRef(surface);
+  const title = getTitle(surface);
+  const tty = findTtyValue(surface);
+  const parts = [];
+  if (ref) parts.push(ref);
+  if (title) {
+    const compact = title.length > 80 ? `${title.slice(0, 77)}...` : title;
+    parts.push(`"${compact}"`);
+  }
+  if (tty) parts.push(`tty=${tty}`);
+  return parts.length > 0 ? parts.join(' ') : null;
+}
+
+function readCmuxTree(options = {}) {
+  const execFile = options.execFileSync || execFileSync;
+  try {
+    execFile('cmux', ['ping'], { timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch {
+    return { ok: false, reason: 'cmux_unreachable' };
+  }
+  try {
+    const raw = execFile('cmux', ['tree', '--json', '--all'], {
+      timeout: 5000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return { ok: true, tree: JSON.parse(raw) };
+  } catch {
+    return { ok: false, reason: 'cmux_tree_unavailable' };
+  }
+}
+
+// cmux currently does not expose a direct "foreground PTY for selected surface" contract.
+// Prefer any tty surfaced by metadata, and only fall back to the telepty title/ref marker
+// proxy. Unknown observations stay unknown so INV-17 never emits on indeterminate state.
+function detectSurfaceMismatch(session, options = {}) {
+  const sessionId = options.sessionId || session?.id;
+  if (!session || session.type !== 'wrapped' || session.backend !== 'cmux') {
+    return { status: 'unknown', reason: 'not_wrapped_cmux' };
+  }
+  if (!isCmuxRef(session.cmuxWorkspaceId)) {
+    return { status: 'unknown', reason: 'missing_workspace' };
+  }
+  const expectedPtyPid = getExpectedPtyPid(session);
+  if (!expectedPtyPid) {
+    return { status: 'unknown', reason: 'missing_expected_pty', expectedPtyPid: null };
+  }
+  if (!isPtyPidAlive(expectedPtyPid, options)) {
+    return { status: 'unknown', reason: 'expected_pty_dead', expectedPtyPid };
+  }
+  const expectedTty = readProcessTty(expectedPtyPid, options);
+  if (!expectedTty) {
+    return { status: 'unknown', reason: 'expected_tty_unknown', expectedPtyPid };
+  }
+
+  const treeResult = readCmuxTree(options);
+  if (!treeResult.ok) {
+    return { status: 'unknown', reason: treeResult.reason, expectedPtyPid, expectedTty };
+  }
+  const workspace = findWorkspace(treeResult.tree, session, sessionId);
+  if (!workspace) {
+    return { status: 'unknown', reason: 'workspace_not_found', expectedPtyPid, expectedTty };
+  }
+  const surface = findSelectedSurface(workspace);
+  if (!surface) {
+    return { status: 'unknown', reason: 'selected_surface_not_found', expectedPtyPid, expectedTty };
+  }
+
+  const observedSurface = formatObservedSurface(surface);
+  if (!observedSurface) {
+    return { status: 'unknown', reason: 'observed_surface_unknown', expectedPtyPid, expectedTty };
+  }
+  const observedSurfaceRef = getSurfaceRef(surface);
+  const observedSurfaceTitle = getTitle(surface);
+  const observedSurfaceTty = findTtyValue(surface);
+  const common = {
+    expectedPtyPid,
+    expectedTty,
+    observedSurface,
+    observedSurfaceRef: observedSurfaceRef || null,
+    observedSurfaceTitle: observedSurfaceTitle || null,
+    observedSurfaceTty: observedSurfaceTty || null
+  };
+
+  if (observedSurfaceTty) {
+    if (observedSurfaceTty === expectedTty) {
+      return { status: 'match', reason: 'tty_match', method: 'tty', ...common };
+    }
+    return { status: 'mismatch', reason: 'tty_mismatch', method: 'tty', ...common };
+  }
+
+  if (session.cmuxSurfaceId && observedSurfaceRef && !stringMatchesRef(observedSurfaceRef, session.cmuxSurfaceId)) {
+    return { status: 'mismatch', reason: 'surface_ref_mismatch', method: 'title', ...common };
+  }
+  if (observedSurfaceTitle && !titleHasSessionMarker(observedSurfaceTitle, sessionId)) {
+    return { status: 'mismatch', reason: 'title_marker_missing', method: 'title', ...common };
+  }
+  if (!observedSurfaceTitle && !observedSurfaceRef) {
+    return { status: 'unknown', reason: 'title_fallback_unavailable', ...common };
+  }
+  return { status: 'match', reason: 'title_marker_match', method: 'title', ...common };
+}
+
 // Terminal-surface CLOSE is owned by the orchestrator's Workspace Host adapter
 // (workspace-host.sh `wh_close`), per the 2026-05-30 surface-ownership verdict — telepty
 // probes liveness and emits `surface_orphaned`, it does not actuate surface close on the
@@ -201,5 +539,6 @@ module.exports = {
   invalidateCache,
   clearCache,
   isSurfaceAlive,
+  detectSurfaceMismatch,
   closeSurface
 };