@mmmbuto/nexuscrew 0.9.38 → 0.9.40

package/lib/proxy/federation.js

@@ -2,6 +2,7 @@
 
 const http = require('node:http');
 const net = require('node:net');
+const crypto = require('node:crypto');
 const express = require('express');
 const { WebSocketServer } = require('ws');
 const store = require('../nodes/store.js');
@@ -1497,7 +1498,7 @@ function localRouter({ nodesPath, localPort, localCredential, readonly, hopSecre
   return r;
 }
 
-function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredential, ingress, readonly = () => false, activeSockets = null, hopSecret = null }) {
+function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredential, ingress, readonly = () => false, activeSockets = null, hopSecret = null, hubAttaches = null }) {
   if (readonly()) return reject(socket, 403);
   const parsed = parseRoute(req.url.replace(/^\/(?:api\/route|federation\/route)/, ''));
   // Due percorsi separati: questo NON passa da routeHandler e non ne condivide i
@@ -1516,6 +1517,16 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
   if (!st) return reject(socket, 503);
   const visited = controlledVisited(req, ingress, st.nodeId);
   if (!visited) return reject(socket, 409);
+  // L'id e la sessione viaggiano SOLO nella query (niente de-mascheramento dei
+  // frame); il token si confronta per IMPRONTA e non entra mai in chiaro.
+  const attachId = parseAttachId(queryParam(req.url, 'attachId'));
+  const attachSession = parseAttachSession(queryParam(req.url, 'attachSession'));
+  // Sul percorso del browser il token e' in query; su quello FEDERATO e' il
+  // Bearer del peer che ha originato l'attach (la query non lo porta). Senza
+  // questo, l'ingresso federato non entrava mai nel ramo trattenuto.
+  const attachToken = queryParam(req.url, 'token') || bearerFrom(req) || null;
+  const attachRoute = parsed.route.join('/');
+  const hubMode = Boolean(hubAttaches && attachId && attachSession && attachToken);
   let port = typeof localPort === 'function' ? localPort() : localPort; let credential = localCredential();
   // Ultimo hop: `/ws` entra com'e', il pannello rientra nell'API locale.
   let path = parsed.resource === '/ws' ? '/ws' : `/api${parsed.resource}`;
@@ -1527,7 +1538,71 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
     const rest = parsed.route.slice(1);
     path = `/federation/route/${rest.length ? `${rest.join('/')}/` : ''}${ROUTE_DELIMITER}${parsed.resource}`;
   }
+  // Aggancio alla attach trattenuta — SOLO dopo i gate d'ingresso appena
+  // eseguiti (route/next/privateInbound/canTransit) e SOLO se il record e'
+  // STACCATO: un secondo upgrade con la stessa identita' non deve rubare lo
+  // stream a un client ancora connesso.
+  if (hubMode) {
+    const record = hubAttaches.take({
+      attachId, tokenHash: tokenFingerprint(attachToken), route: attachRoute, session: attachSession,
+    });
+    if (record) {
+      const handshake = wsHandshakeResponse(req);
+      if (!handshake) return reject(socket, 403);
+      // 101 a mano, poi passthrough: l'input del nuovo client passa com'e' e
+      // l'upstream de-maschera per frame (la chiave di mascheramento puo'
+      // cambiare), l'output va scritto grezzo (i frame li ha gia' incorniciati
+      // l'upstream).
+      try { socket.write(handshake); } catch (_) { /* morto */ }
+      // Gli eventuali byte gia' arrivati dopo la richiesta di upgrade vanno
+      // inoltrati come nel ramo normale, non persi.
+      if (head && head.length) { try { record.up.write(head); } catch (_) { /* morto */ } }
+      socket.pipe(record.up, { end: false });
+      // Identity check: la caduta di QUESTO socket non deve staccare il record
+      // se nel frattempo ne ha preso uno nuovo.
+      const onGoneResume = () => { if (record.socket === socket) hubAttaches.detach(record); };
+      socket.on('end', onGoneResume);
+      socket.on('close', onGoneResume);
+      socket.on('error', () => { /* il close segue */ });
+      // Anche questo socket entra in activeSockets, o la chiusura ordinata
+      // del server non lo vede.
+      if (activeSockets && typeof activeSockets.add === 'function') {
+        activeSockets.add(socket); activeSockets.add(record.up);
+        const remove = () => { activeSockets.delete(socket); activeSockets.delete(record.up); };
+        socket.once('close', remove); record.up.once('close', remove);
+      }
+      hubAttaches.attach(record, socket);
+      return;
+    }
+  }
   const up = net.connect({ host: '127.0.0.1', port });
+  // Osservatore NON consumante della testa di risposta dell'upstream: serve
+  // solo a sapere se il 101 e' transitato (client in stato WebSocket) o se
+  // l'hop e' morto prima. La pipe resta l'unico trasporto dei byte: il
+  // listener non sottrae nulla, guarda gli stessi chunk.
+  let saw101 = false;
+  let headBuf = Buffer.alloc(0);
+  let gone = false;
+  up.on('data', (chunk) => {
+    if (saw101 || headBuf.length >= 1024) return;
+    headBuf = Buffer.concat([headBuf, chunk.subarray(0, Math.max(0, 1024 - headBuf.length))]);
+    if (headBuf.includes(' 101')) saw101 = true;
+  });
+  // L'hop e' morto (errore di connessione o chiusura a stream avviato): il
+  // client deve riceverlo come codice, non come troncamento.
+  const upstreamGone = () => {
+    if (gone) return;
+    gone = true;
+    if (saw101) {
+      // Handshake gia' transitato: un frame di close e' cio' che il browser
+      // sa leggere. Se l'upstream aveva gia' chiuso con un suo codice, quel
+      // frame e' arrivato prima e vince (il browser si ferma al primo).
+      try { socket.write(wsCloseFrame(4402, 'upstream gone')); } catch (_) { /* socket morto */ }
+      try { socket.end(); } catch (_) { /* idem */ }
+      return;
+    }
+    acceptWsThenClose(socket, req, 4402, 'upstream gone');
+  };
   up.once('connect', () => {
     // Ultimo hop: l'upgrade rientra nell'API locale col Bearer locale e da li'
     // in poi sarebbe indistinguibile da un attach diretto di chi possiede quel
@@ -1554,9 +1629,49 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
       const remove = () => { activeSockets.delete(socket); activeSockets.delete(up); };
       socket.once('close', remove); up.once('close', remove);
     }
-    socket.pipe(up); up.pipe(socket);
+    if (hubMode) {
+      // Attach trattenuta: l'output passa dal ring quando il client non c'è,
+      // e il record entra nello store sotto la sua identità.
+      const record = hubAttaches.hold({
+        attachId, tokenHash: tokenFingerprint(attachToken), route: attachRoute, session: attachSession, up,
+      });
+      up.on('data', (chunk) => hubAttaches.feed(record, chunk));
+      up.on('close', () => hubAttaches.destroy(record));
+      up.on('error', () => hubAttaches.destroy(record));
+      // end:false: la caduta del CLIENT non deve chiudere l'upstream — è
+      // esattamente ciò che la grazia deve trattenere.
+      socket.pipe(up, { end: false });
+      hubAttaches.attach(record, socket);
+      // Senza un handler d'errore il RST del client morto resta senza 'close':
+      // la caduta non verrebbe mai rilevata e la grazia non partirebbe.
+      socket.on('error', () => { /* il close segue */ });
+      // 'end' E 'close': con la pipe a end:false il socket resta HALF-OPEN
+      // quando il browser se ne va, quindi il solo 'close' puo' non arrivare
+      // mai e la grazia non partirebbe. Il FIN in lettura e' la caduta.
+      const onGoneHeld = () => { if (record.socket === socket) hubAttaches.detach(record); };
+      socket.on('end', onGoneHeld);
+      socket.on('close', onGoneHeld);
+      if (activeSockets && typeof activeSockets.add === 'function') {
+        activeSockets.add(socket); activeSockets.add(up);
+        const remove = () => { activeSockets.delete(socket); activeSockets.delete(up); };
+        socket.once('close', remove); up.once('close', remove);
+      }
+      return;
+    }
+    socket.pipe(up);
+    // end:false: la chiusura verso il browser la governiamo noi, o la pipe
+    // chiuderebbe il socket PRIMA che il frame di close 4402 possa partire.
+    up.pipe(socket, { end: false });
   });
-  up.on('error', () => reject(socket, 502)); socket.on('error', () => up.destroy());
+  if (!hubMode) {
+    // Nel ramo trattenuto la morte dell'upstream la governa lo store (destroy
+    // del record): qui il close leggibile verso il browser non ha più un
+    // destinatario quando il client è già caduto.
+    up.on('error', () => upstreamGone());
+    up.on('end', () => upstreamGone());
+    up.on('close', () => upstreamGone());
+  }
+  socket.on('error', () => up.destroy());
 }
 
 // Indistinguibile da «sessione inesistente» (lib/ws/bridge.js): le stesse
@@ -1577,13 +1692,220 @@ function rejectAsNoSuchSession(socket, req) {
   } catch (_) { try { socket.destroy(); } catch (_) { /* idem */ } }
 }
 
+// ---- attach trattenuta nell'hub --------------------------------------
+// Quando il client cade, l'upstream federato NON viene distrutto subito: resta
+// vivo per la grazia e il suo output va in un ring. Chi torna con la STESSA
+// identità (hash del token, stessa route, stessa sessione) riprende da qui
+// senza riaprire l'attach; chiunque altro fa una attach nuova.
+const HUB_ATTACH_MAX = 8;
+const HUB_ATTACH_GRACE_MS = 60000;
+const HUB_ATTACH_RING_BYTES = 256 * 1024;
+
+function queryParam(url, name) {
+  const q = String(url || '').split('?')[1];
+  if (!q) return null;
+  for (const part of q.split('&')) {
+    const i = part.indexOf('=');
+    if (i <= 0) continue;
+    let key = part.slice(0, i);
+    try { key = decodeURIComponent(key); } catch (_) { /* chiave grezza */ }
+    if (key !== name) continue;
+    try { return decodeURIComponent(part.slice(i + 1)); } catch (_) { return part.slice(i + 1); }
+  }
+  return null;
+}
+// 128 bit in esadecimale, e nient'altro: un id malformato non è un attachId.
+const ATTACH_ID_RE = /^[0-9a-f]{32}$/;
+const parseAttachId = (raw) => (typeof raw === 'string' && ATTACH_ID_RE.test(raw) ? raw : null);
+// Nome sessione con lo stesso alfabeto accettato dalle risorse federate.
+const ATTACH_SESSION_RE = /^[\w.@%:+-]{1,128}$/;
+const parseAttachSession = (raw) => (typeof raw === 'string' && ATTACH_SESSION_RE.test(raw) ? raw : null);
+// Il token non entra MAI in memoria in chiaro: si confronta la sua impronta.
+const tokenFingerprint = (token) => crypto.createHash('sha256').update(String(token)).digest('hex');
+// Diagnostica: mai l'id completo, mai il token.
+const shortId = (id) => (typeof id === 'string' ? id.slice(0, 6) : '-');
+
+// Ricompone i confini di frame del protocollo WS leggendo SOLO la lunghezza
+// dall'header. Server->client non e' mascherato; se lo fosse, l'header e' piu'
+// lungo e i 4 byte di maschera si saltano senza toccare il payload.
+function createFrameSplitter() {
+  let buf = Buffer.alloc(0);
+  return {
+    push(chunk) {
+      buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+      const frames = [];
+      let off = 0;
+      while (off + 2 <= buf.length) {
+        const b1 = buf[off + 1];
+        let len = b1 & 0x7f;
+        let head = 2;
+        if (len === 126) {
+          if (off + 4 > buf.length) break;
+          len = buf.readUInt16BE(off + 2); head = 4;
+        } else if (len === 127) {
+          if (off + 10 > buf.length) break;
+          len = Number(buf.readBigUInt64BE(off + 2)); head = 10;
+        }
+        if (b1 & 0x80) head += 4;
+        const total = head + len;
+        if (off + total > buf.length) break;
+        frames.push(buf.subarray(off, off + total));
+        off += total;
+      }
+      buf = off ? buf.subarray(off) : buf;
+      return frames;
+    },
+    pending: () => buf,
+  };
+}
+
+function createHubAttachStore({ graceMs = HUB_ATTACH_GRACE_MS, maxAttaches = HUB_ATTACH_MAX, ringBytes = HUB_ATTACH_RING_BYTES } = {}) {
+  const grace = Math.max(1, Number(graceMs) || HUB_ATTACH_GRACE_MS);
+  const cap = Math.max(1, Math.floor(Number(maxAttaches) || HUB_ATTACH_MAX));
+  const ringLimit = Math.max(1, Math.floor(Number(ringBytes) || HUB_ATTACH_RING_BYTES));
+  const records = new Map();
+
+  const destroy = (record) => {
+    if (!record || record.ended) return;
+    record.ended = true;
+    if (record.timer) { clearTimeout(record.timer); record.timer = null; }
+    if (records.get(record.attachId) === record) records.delete(record.attachId);
+    // Se un client e' ATTACCATO, la morte dell'upstream va DETTA subito: senza,
+    // il browser resta appeso finche' la liveness non scade (10 s) — e in
+    // 0.9.39 il 4402 arrivava invece immediatamente. Se nessuno e' attaccato
+    // non c'e' nulla da avvisare.
+    if (record.socket && record.socket.writable) {
+      try { record.socket.write(wsCloseFrame(4402, 'upstream gone')); } catch (_) { /* morto */ }
+      try { record.socket.end(); } catch (_) { /* idem */ }
+      record.socket = null;
+    }
+    try { record.up.destroy(); } catch (_) { /* già chiuso */ }
+  };
+  // Il ring tiene FRAME INTERI: un ring di soli chunk TCP puo' consegnare un
+  // replay che comincia a meta' frame, e il browser chiude con 1002. Il parser
+  // legge SOLO la lunghezza dagli header (server->client non maschera) e non
+  // tocca i payload: nessun de-mascheramento.
+  const pushRing = (record, frame) => {
+    record.ring.push(frame);
+    record.ringBytes += frame.length;
+    while (record.ringBytes > ringLimit && record.ring.length > 1) record.ringBytes -= record.ring.shift().length;
+  };
+  const hold = ({ attachId, tokenHash, route, session, up }) => {
+    // Cap: si chiude la PIÙ VECCHIA, non si rifiuta la nuova.
+    while (records.size >= cap) {
+      const oldest = records.keys().next().value;
+      const rec = oldest ? records.get(oldest) : null;
+      if (!rec) break;
+      destroy(rec);
+    }
+    const record = {
+      attachId, tokenHash, route, session, up, socket: null,
+      ring: [], ringBytes: 0, timer: null, ended: false, splitter: createFrameSplitter(),
+    };
+    records.set(attachId, record);
+    return record;
+  };
+  // Scrive il pregresso al nuovo client: prima il ring, poi lo stream live.
+  const attach = (record, socket) => {
+    if (!record || record.ended) return false;
+    if (record.timer) { clearTimeout(record.timer); record.timer = null; }
+    record.socket = socket;
+    for (const frame of record.ring) { try { socket.write(frame); } catch (_) { break; } }
+    // I byte già letti ma non ancora completati in un frame vanno consegnati
+    // ora: senza, il client perderebbe la coda dell'ultimo frame.
+    const pending = record.splitter.pending();
+    if (pending && pending.length) { try { socket.write(pending); } catch (_) { /* morto */ } }
+    record.splitter = createFrameSplitter();
+    record.ring = []; record.ringBytes = 0;
+    return true;
+  };
+  // Il client è caduto: da qui l'output va nel ring, e parte la grazia.
+  const detach = (record) => {
+    if (!record || record.ended) return;
+    record.socket = null;
+    if (record.timer) clearTimeout(record.timer);
+    record.timer = setTimeout(() => destroy(record), grace);
+    if (typeof record.timer.unref === 'function') record.timer.unref();
+  };
+  const feed = (record, chunk) => {
+    if (!record || record.ended) return;
+    if (record.socket && record.socket.writable) {
+      // Passthrough: i byte vanno al client come sono arrivati.
+      try { record.socket.write(chunk); return; } catch (_) { /* cade: si passa al ring */ }
+    }
+    for (const frame of record.splitter.push(chunk)) pushRing(record, frame);
+  };
+  // Aggancio: SOLO identità identica (impronta token, route, sessione).
+  const take = ({ attachId, tokenHash, route, session }) => {
+    const record = records.get(attachId);
+    if (!record || record.ended) return null;
+    // Solo un record STACCATO (in grazia): agganciare un record ancora
+    // attaccato vorrebbe dire rubare lo stream a un client vivo. Un socket
+    // DITRUTTO non e' un client vivo — e il suo 'close' puo' arrivare dopo,
+    // quindi lo stato del socket e' la verita' osservabile, non l'evento.
+    if (record.socket && record.socket.destroyed !== true) return null;
+    if (record.tokenHash !== tokenHash || record.route !== route || record.session !== session) return null;
+    return record;
+  };
+  return {
+    hold, attach, detach, feed, take, destroy,
+    size: () => records.size,
+    get: (id) => records.get(id) || null,
+  };
+}
+
+// Handshake WS del ramo di ripresa: identico a quello che scrive REJECT_WSS
+// (stesso Sec-WebSocket-Accept), ma SENZA creare un oggetto ws. Il socket del
+// nuovo client resta un PASSTHROUGH di frame come nel ramo normale: niente
+// de-mascheramento, niente re-incapsulamento.
+const WS_ACCEPT_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+function wsHandshakeResponse(req) {
+  const key = req && req.headers && req.headers['sec-websocket-key'];
+  if (!key) return null;
+  const accept = crypto.createHash('sha1').update(String(key) + WS_ACCEPT_GUID).digest('base64');
+  return 'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n'
+    + `Sec-WebSocket-Accept: ${accept}\r\n\r\n`;
+}
+
 function reject(socket, code) { try { socket.end(`HTTP/1.1 ${code} Error\r\nConnection: close\r\n\r\n`); } catch (_) {} }
 
+// Frame di close costruito a mano: sul ramo "hop morto DOPO il 101" non c'e'
+// piu' una richiesta di upgrade da consegnare a handleUpgrade (l'handshake e'
+// gia' transitato), quindi il frame va scritto direttamente.
+function wsCloseFrame(code, reason = '') {
+  const text = String(reason).slice(0, 100);
+  const payload = Buffer.alloc(2 + Buffer.byteLength(text));
+  payload.writeUInt16BE((Number(code) || 1000) & 0xffff, 0);
+  payload.write(text, 2, 'utf8');
+  const len = payload.length;
+  return len < 126
+    ? Buffer.concat([Buffer.from([0x88, len]), payload])
+    : Buffer.concat([Buffer.from([0x88, 126, (len >> 8) & 0xff, len & 0xff]), payload]);
+}
+
+// Hop morto e il client NON ha ancora visto il 101: completiamo l'handshake
+// qui, cosi' il browser entra in stato WebSocket e puo' leggere un frame di
+// close LEGGIBILE (4402) invece di un 502 grezzo o di un EOF muto. L'accept
+// lo calcola la libreria (stesso REJECT_WSS del rifiuto "no such session"),
+// cosi' il GUID della RFC 6455 non vive in questo file. Per una richiesta che
+// non e' un vero upgrade resta il rifiuto HTTP di prima.
+function acceptWsThenClose(socket, req, code, reason) {
+  const key = req && req.headers && req.headers['sec-websocket-key'];
+  if (!key) return reject(socket, 502);
+  try {
+    REJECT_WSS.handleUpgrade(req, socket, Buffer.alloc(0), (ws) => {
+      try { ws.send(JSON.stringify({ type: 'error', reason })); } catch (_) { /* socket morto */ }
+      try { ws.close(code, reason); } catch (_) { /* idem */ }
+    });
+  } catch (_) { try { socket.destroy(); } catch (_) { /* idem */ } }
+}
+
+
 module.exports = {
   isPanelResource, panelAllowedFor, isLiveHostResource, liveHostAllowedFor, routeHandler,
   MAX_HOPS, ROUTE_DELIMITER, TOPOLOGY_PEER_TIMEOUT_MS, SHARE_NOT_READY_CODE, classifyShareFailure, activeReversePort,
   peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource, allowedQuery, readonlyBlocksFederated,
-  collectTopology, collectTopologyDetailed, collectLocalTopology, peerRouter, localRouter, forwardUpgrade,
+  collectTopology, collectTopologyDetailed, collectLocalTopology, peerRouter, localRouter, forwardUpgrade, createHubAttachStore,
   probeHealth, waitForHealthyPeer, canListenLoopback, preflightHubReverse, notifyHubShare, reconcilePeerShare, runShareRevokeBoot, probeReverseOwner,
   hubPoolRequest, verifyHubPoolSlot, reserveHubPoolSlot, commitHubPoolSlot, settleHubPoolSlot, abortHubPoolSlot, getHubPoolStatus,
 };

package/lib/server.js

@@ -110,8 +110,28 @@ function uiBuildVersion(distDir) {
   } catch (_) { return null; }
 }
 
+// I defaults del bridge ws vengono dalla config del server. E' una funzione a
+// se' perche' il cablaggio sia verificabile senza montare una sessione tmux.
+function wsBridgeDefaults(cfg = {}) {
+  const terminal = cfg.terminal && typeof cfg.terminal === 'object' ? cfg.terminal : {};
+  return {
+    readonlyDefault: cfg.readonlyDefault,
+    tmuxBin: cfg.tmuxBin,
+    outputRingBytes: terminal.outputRingBytes || undefined,
+    captureLines: terminal.captureLines || undefined,
+  };
+}
+
 function createServer(opts = {}) {
   const cfg = loadConfig(opts);
+  // UNA istanza per server: trattiene le attach federate quando il client cade,
+  // cosi' chi torna con la stessa identita' riprende dal buffer. I parametri
+  // vengono dalla config del server, non da valori cablati.
+  const hubAttaches = federation.createHubAttachStore({
+    graceMs: cfg.terminal && cfg.terminal.hubGraceMs,
+    ringBytes: cfg.terminal && cfg.terminal.outputRingBytes,
+    maxAttaches: 8,
+  });
   assertLoopback(cfg.bind);
   // Token holder LIVE (da revisione di sicurezza): requireToken/verify leggono tokenStore.get()
   // ad ogni richiesta, cosi' una rotazione via Settings API invalida il VECCHIO token
@@ -1035,6 +1055,9 @@ function createServer(opts = {}) {
     instanceId: (nodesStore.loadStore(nodesPath) || {}).nodeId || null,
     nodePanelPorts: nodePanelPorts(),
     presets: ['shell', 'claude', 'codex-vl', 'pi', ...Object.keys(cfg.sessionPresets || {})],
+    // i parametri del terminale sono configurabili dal server e leggibili
+    // dal client (che ne ha comunque i default iniettabili).
+    terminal: cfg.terminal || null,
   }));
   const apiNodeId = () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
   const identityMode = cfg.fleetIdentityMode || cfg.fleet?.identity?.mode || 'legacy';
@@ -1672,13 +1695,13 @@ function createServer(opts = {}) {
       const panelFederato = /^\/api\/route\/[^?#]*\/_\/panel\/[A-Za-z0-9._-]{1,32}(?:\/.*)?$/.test(pathname)
         && /(?:^|;\s*)npanel=/.test(String(req.headers.cookie || ''));
       if (!panelFederato && !verify(tokenHolder.value, given)) return socket.destroy();
-      federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: runtimePort, localCredential: () => tokenHolder.value, ingress: null, readonly: proxyReadonly, activeSockets: proxySockets, hopSecret: () => hopSecret });
+      federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: runtimePort, localCredential: () => tokenHolder.value, ingress: null, readonly: proxyReadonly, activeSockets: proxySockets, hopSecret: () => hopSecret, hubAttaches });
       return;
     }
     if (pathname.startsWith('/federation/route/')) {
       const ingress = federation.peerFromToken(nodesPath, bearerFrom(req));
       if (!ingress) return socket.destroy();
-      federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: runtimePort, localCredential: () => tokenHolder.value, ingress, readonly: proxyReadonly, activeSockets: proxySockets, hopSecret: () => hopSecret });
+      federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: runtimePort, localCredential: () => tokenHolder.value, ingress, readonly: proxyReadonly, activeSockets: proxySockets, hopSecret: () => hopSecret, hubAttaches });
       return;
     }
     if (pathname.startsWith('/api/panel/')) {
@@ -1732,7 +1755,7 @@ function createServer(opts = {}) {
       isValidSession: (name) => sessionExistsImpl(name) && wsScope.allowsSession(name),
       runAction: (sess, action) => runAction(cfg.tmuxBin, sess, action),
       countClients: (sess) => attachedClients(cfg.tmuxBin, sess),
-      defaults: { readonlyDefault: cfg.readonlyDefault, tmuxBin: cfg.tmuxBin },
+      defaults: wsBridgeDefaults(cfg),
       ptyGrace,
       onAttach: (sess) => attachedWs.set(ws, sess),
       diagnostics,
@@ -1861,4 +1884,4 @@ function start(opts = {}) {
   return server;
 }
 
-module.exports = { createServer, start };
+module.exports = { createServer, start, wsBridgeDefaults };

package/lib/ws/bridge.js

@@ -117,8 +117,59 @@ function sendJson(ws, value) {
   try { ws.send(JSON.stringify(value)); } catch (_) {}
 }
 
+// Ripresa per sequenza : i frame di output sono numerati e l'ultimo tratto
+// resta in un ring per sessione, cosi' un client che torna puo' chiedere SOLO
+// il mancante invece di ridipingere tutto (o peggio, perdere il tratto).
+const OUTPUT_RING_BYTES = 256 * 1024;
+function createOutputRing({ maxBytes = OUTPUT_RING_BYTES } = {}) {
+  const limit = Math.max(1, Math.floor(Number(maxBytes) || OUTPUT_RING_BYTES));
+  const frames = [];
+  let bytes = 0;
+  let nextSeq = 0;
+  return {
+    push(data) {
+      const buf = Buffer.from(data);
+      const seq = nextSeq++;
+      frames.push({ seq, data: buf });
+      bytes += buf.length;
+      while (bytes > limit && frames.length > 1) bytes -= frames.shift().data.length;
+      return seq;
+    },
+    // Frame che il client (fermo a `seq`) non ha ancora visto. `null` quando il
+    // buco NON e' coperto: inventare un delta parziale corromperebbe lo schermo.
+    since(seq) {
+      const wanted = Number(seq);
+      if (!Number.isInteger(wanted) || wanted < 0) return null;
+      if (wanted + 1 >= nextSeq) return [];
+      if (!frames.length || frames[0].seq > wanted + 1) return null;
+      return frames.filter((f) => f.seq > wanted);
+    },
+    get nextSeq() { return nextSeq; },
+  };
+}
+
+// Ogni frame di output porta il suo seq nei primi 4 byte (big endian).
+function frameWithSeq(seq, data) {
+  const head = Buffer.alloc(4);
+  head.writeUInt32BE((Number(seq) || 0) >>> 0, 0);
+  return Buffer.concat([head, Buffer.from(data)]);
+}
+
+// Resync del buffer dopo una riconnessione: il client chiede {type:'resync'}
+// e riceve l'intero pane (scrollback cap 2000 righe) con le sequenze di
+// escape (-e) per ridipingere lo schermo senza mai mostrarlo vuoto.
+const RESYNC_MAX_LINES = 2000;
+function defaultCapturePane(session, tmuxBin, captureLines, cb) {
+  const lines = Math.max(1, Math.floor(Number(captureLines) || RESYNC_MAX_LINES));
+  try {
+    require('node:child_process').execFile(tmuxBin || 'tmux',
+      ['capture-pane', '-e', '-p', '-S', `-${lines}`, '-t', String(session)],
+      { maxBuffer: 16 * 1024 * 1024 }, (err, stdout) => cb(err, stdout));
+  } catch (e) { cb(e); }
+}
+
 function bindWs(ws, deps) {
-  const { openAttach, verifyToken, isValidSession = () => true, runAction = () => false, countClients = () => 0, defaults = {}, onAttach = () => {}, ptyGrace = null, diagnostics = null, dropCounter = null } = deps;
+  const { openAttach, verifyToken, isValidSession = () => true, runAction = () => false, countClients = () => 0, defaults = {}, onAttach = () => {}, ptyGrace = null, diagnostics = null, dropCounter = null, capturePane = defaultCapturePane } = deps;
   let record = null;
   let attached = false;
   let session = null;
@@ -218,6 +269,7 @@ function bindWs(ws, deps) {
         onAttach(session, ws);
         logReattach();
         sendJson(ws, { type: 'attached', reconnectToken: record.resumeToken });
+        sendJson(ws, { type: 'link', state: 'live' });
         return;
       }
       attached = true;
@@ -254,6 +306,7 @@ function bindWs(ws, deps) {
         session: msg.session,
         readonly: defaults.readonlyDefault === true || !!msg.readonly,
         takeSize,
+        ring: createOutputRing({ maxBytes: defaults.outputRingBytes }),
         ended: false,
         exitCode: undefined,
         resumeToken: null,
@@ -264,8 +317,11 @@ function bindWs(ws, deps) {
       if (ptyGrace) record.resumeToken = ptyGrace.issueToken(record);
       onAttach(session, ws);
       record.pty.onData((d) => {
+        // Il ring registra SEMPRE: anche mentre nessuno e' attaccato l'output
+        // resta disponibile per chi torna con {type:'resume'}.
+        const seq = record.ring.push(d);
         if (!record.ws) return;
-        try { record.ws.send(Buffer.from(d), { binary: true }); } catch (_) { return; }
+        try { record.ws.send(frameWithSeq(seq, d), { binary: true }); } catch (_) { return; }
         if ((record.ws.bufferedAmount || 0) > MAX_BUFFERED) fail(1011, 'backpressure');
       });
       record.pty.onExit((info) => {
@@ -279,6 +335,7 @@ function bindWs(ws, deps) {
         try { record.ws.close(1000, 'exit'); } catch (_) {}
       });
       sendJson(ws, { type: 'attached', reconnectToken: record.resumeToken });
+      sendJson(ws, { type: 'link', state: 'live' });
       return;
     }
     // dopo l'attach
@@ -294,6 +351,32 @@ function bindWs(ws, deps) {
     else if (msg.type === 'input' && !record.readonly) record.pty.write(typeof msg.data === 'string' ? msg.data : '');
     else if (msg.type === 'key' && !record.readonly) record.pty.write(typeof msg.seq === 'string' ? msg.seq.slice(0, 64) : '');
     else if (msg.type === 'action') runAction(session, msg.name); // nav window/pane server-side
+    // Liveness applicativa: il ping risponde SEMPRE, anche a sessione muta, e
+    // senza toccare il PTY. È il segnale che distingue una connessione viva da
+    // una mezzo-aperta (il tunnel morto senza FIN non produce nessun close).
+    else if (msg.type === 'ping') sendJson(ws, { type: 'pong', t: msg.t });
+    // Ripresa: rimanda solo il tratto che il client non ha visto. Se il buco
+    // non e' coperto dal ring si chiede il repaint, mai un delta parziale.
+    else if (msg.type === 'resume') {
+      const missing = record.ring.since(msg.seq);
+      if (missing === null) {
+        sendJson(ws, { type: 'resync-needed' });
+      } else {
+        for (const frame of missing) {
+          try { ws.send(frameWithSeq(frame.seq, frame.data), { binary: true }); } catch (_) { break; }
+        }
+        sendJson(ws, { type: 'link', state: 'live' });
+      }
+    }
+    // Resync post-riconnessione: ridipinge il buffer del client dal pane
+    // reale. Best-effort — se il capture fallisce lo stream live continua e
+    // il client resta sul buffer che aveva (mai uno schermo vuoto forzato).
+    else if (msg.type === 'resync') {
+      capturePane(session, defaults.tmuxBin || 'tmux', defaults.captureLines, (err, text) => {
+        if (err) return;
+        sendJson(ws, { type: 'snapshot', data: String(text || '') });
+      });
+    }
   }
 
   // Alla riconnessione la DURATA della caduta e' il gap close->reopen della

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.9.38",
+  "version": "0.9.40",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {