@mmmbuto/nexuscrew 0.9.14 → 0.9.16

package/lib/ws/bridge.js

@@ -1,4 +1,5 @@
 'use strict';
+const crypto = require('node:crypto');
 // Bridges ONE WebSocket to ONE PTY attach. Dependencies are injectable for tests.
 // Hardening: close on protocol violation, no 2nd attach, clamp cols/rows,
 // validated session, backpressure cutoff, errors as JSON with a code.
@@ -11,19 +12,157 @@ function clamp(n, lo, hi, def) {
 }
 
 const ATTACH_TIMEOUT_MS = 15000;
+// Mobile handovers and tunnel renegotiation can last longer than a LAN retry.
+// Thirty seconds is finite but configurable, so a small host can tune the
+// trade-off without making the suspended PTY lifetime unbounded.
+const PTY_GRACE_MS = 30000;
+const PTY_GRACE_MAX_SESSIONS = 8;
+// No PTY output is buffered while detached; this bounds the retained record,
+// rather than pretending a stale output buffer is a current terminal screen.
+const PTY_GRACE_RECORD_BYTES = 1024;
+const PTY_GRACE_MAX_MEMORY_BYTES = PTY_GRACE_MAX_SESSIONS * PTY_GRACE_RECORD_BYTES;
+
+function createPtyGraceStore({
+  graceMs = PTY_GRACE_MS,
+  maxSessions = PTY_GRACE_MAX_SESSIONS,
+  maxMemoryBytes = PTY_GRACE_MAX_MEMORY_BYTES,
+  recordBytes = PTY_GRACE_RECORD_BYTES,
+  randomBytes = crypto.randomBytes,
+} = {}) {
+  const suspended = new Map();
+  const sessionLimit = Math.max(1, Math.floor(Number(maxSessions) || PTY_GRACE_MAX_SESSIONS));
+  const memoryLimit = Math.max(1, Math.floor(Number(maxMemoryBytes) || PTY_GRACE_MAX_MEMORY_BYTES));
+  const retainedRecordBytes = Math.max(1, Math.floor(Number(recordBytes) || PTY_GRACE_RECORD_BYTES));
+  let memoryBytes = 0;
+
+  const clearRecordTimer = (record) => {
+    if (record.graceTimer) clearTimeout(record.graceTimer);
+    record.graceTimer = null;
+  };
+
+  const issueToken = (record) => {
+    if (!record.resumeToken) record.resumeToken = randomBytes(32).toString('base64url');
+    return record.resumeToken;
+  };
+
+  const releaseRecord = (token, record) => {
+    if (suspended.get(token) !== record) return false;
+    suspended.delete(token);
+    memoryBytes = Math.max(0, memoryBytes - record.graceBytes);
+    return true;
+  };
+
+  const suspend = (record) => {
+    if (!record || record.ended) return null;
+    const token = issueToken(record);
+    if (!suspended.has(token)
+      && (suspended.size >= sessionLimit || memoryBytes + retainedRecordBytes > memoryLimit)) return null;
+    clearRecordTimer(record);
+    if (!suspended.has(token)) {
+      record.graceBytes = retainedRecordBytes;
+      memoryBytes += retainedRecordBytes;
+    }
+    suspended.set(token, record);
+    record.graceTimer = setTimeout(() => {
+      if (suspended.get(token) !== record) return;
+      releaseRecord(token, record);
+      record.graceTimer = null;
+      record.graceExpired = true;
+      try { record.pty.kill(); } catch (_) {}
+    }, graceMs);
+    if (typeof record.graceTimer.unref === 'function') record.graceTimer.unref();
+    return token;
+  };
+
+  const resume = (token, session) => {
+    if (!token || typeof session !== 'string') return null;
+    const record = suspended.get(token);
+    if (!record || record.ended || record.session !== session || record.ws) return null;
+    releaseRecord(token, record);
+    clearRecordTimer(record);
+    return record;
+  };
+
+  const resumeEnded = (token, session) => {
+    if (!token || typeof session !== 'string') return null;
+    const record = suspended.get(token);
+    if (!record || !record.ended || record.session !== session || record.ws) return null;
+    releaseRecord(token, record);
+    clearRecordTimer(record);
+    return record;
+  };
+
+  const close = () => {
+    for (const record of suspended.values()) {
+      clearRecordTimer(record);
+      try { record.pty.kill(); } catch (_) {}
+    }
+    suspended.clear();
+    memoryBytes = 0;
+  };
+
+  return {
+    issueToken,
+    suspend,
+    resume,
+    resumeEnded,
+    close,
+    size: () => suspended.size,
+    memoryBytes: () => memoryBytes,
+    limits: () => ({ maxSessions: sessionLimit, maxMemoryBytes: memoryLimit }),
+  };
+}
+
+function sendJson(ws, value) {
+  try { ws.send(JSON.stringify(value)); } catch (_) {}
+}
 
 function bindWs(ws, deps) {
-  const { openAttach, verifyToken, isValidSession = () => true, runAction = () => false, countClients = () => 0, defaults = {}, onAttach = () => {} } = deps;
-  let pty = null;
+  const { openAttach, verifyToken, isValidSession = () => true, runAction = () => false, countClients = () => 0, defaults = {}, onAttach = () => {}, ptyGrace = null, diagnostics = null, dropCounter = null } = deps;
+  let record = null;
   let attached = false;
   let session = null;
+  let closeLogged = false;
+  // UNA sola riga diagnostica per socket: la prima chiusura vince. Le
+  // successive (close + error sullo stesso socket) non generano rumore.
+  const logClose = (level, event, message, meta = {}) => {
+    if (closeLogged) return;
+    closeLogged = true;
+    if (!diagnostics) return;
+    try { diagnostics.record(level, 'ws', event, message, { cell: session || undefined, ...meta }); } catch (_) {}
+  };
+  const countDrop = () => {
+    if (!dropCounter) return {};
+    const snap = dropCounter.recordDrop(session);
+    return { drops: snap.drops };
+  };
+
+  const detach = () => {
+    if (!record || record.ws !== ws) return;
+    record.ws = null;
+    if (record.ended) return;
+    if (!ptyGrace) {
+      try { record.pty.kill(); } catch (_) {}
+      return;
+    }
+    if (!ptyGrace.suspend(record)) {
+      // A bounded host refuses another suspended PTY instead of exceeding its
+      // explicit process/memory budget.
+      try { record.pty.kill(); } catch (_) {}
+    }
+  };
 
   function fail(code, reason) {
     // Si spegne anche la scadenza pre-attach: un frame rifiutato (token o
     // handshake non validi) chiude gia' il socket, e lasciare il timer vivo
     // fino al close event tiene in piedi un handle senza scopo.
     clearAttachTimer();
-    try { ws.send(JSON.stringify({ type: 'error', reason })); } catch (_) {}
+    sendJson(ws, { type: 'error', reason });
+    // Chiusura INITIATA DAL SERVER: il motivo e' qui, non nel close event.
+    // Level warn = sempre visibile (non richiede verbose).
+    logClose('warn', 'WS_SERVER_CLOSE', `Server closed socket: ${reason}`, {
+      reason: String(reason).slice(0, 48), closeCode: Number(code) || undefined, ...countDrop(),
+    });
     try { ws.close(code, reason); } catch (_) {}
   }
 
@@ -51,25 +190,55 @@ function bindWs(ws, deps) {
       try { msg = JSON.parse(data.toString()); } catch (_) { return fail(1002, 'bad handshake'); }
       if (msg.type !== 'attach') return fail(1002, 'expected attach');
       if (!verifyToken(msg.token)) return fail(4401, 'bad token');
-      if (!isValidSession(msg.session)) return fail(4404, 'no such session');
+
+      // Authorization precedes every live-PTY resume. A terminated record is
+      // different: its only remaining purpose is to deliver the late exit
+      // outcome, so it has an explicit, non-attach path below.
+      if (!isValidSession(msg.session)) {
+        const ended = ptyGrace && ptyGrace.resumeEnded(msg.reconnectToken, msg.session);
+        if (ended) {
+          clearAttachTimer();
+          sendJson(ws, { type: 'exit', code: ended.exitCode });
+          try { ws.close(1000, 'exit'); } catch (_) {}
+          return;
+        }
+        return fail(4404, 'no such session');
+      }
+
+      // The capability is bound to the authenticated session and can resume
+      // only a still-live PTY. It is never an alternative to isValidSession.
+      const resumed = ptyGrace && ptyGrace.resume(msg.reconnectToken, msg.session);
+      if (resumed) {
+        clearAttachTimer();
+        record = resumed;
+        record.ws = ws;
+        record.readonly = record.readonly || !!msg.readonly;
+        attached = true;
+        session = record.session;
+        onAttach(session, ws);
+        logReattach();
+        sendJson(ws, { type: 'attached', reconnectToken: record.resumeToken });
+        return;
+      }
       attached = true;
       clearAttachTimer();
       session = msg.session;
-      onAttach(session, ws);
+      logReattach();
       // Resize default: when nobody else is attached, drive the session size so a
       // small phone gets a usable (non-clipped) view and clean line editing. When a
       // real terminal is already attached, default to ignore-size so we don't shrink
       // its window. An explicit takeSize from the client always wins.
-      const takeSize = msg.takeSize !== undefined
-        ? !!msg.takeSize
-        : countClients(msg.session) === 0;
       // "Segue il focus": garantisce window-size latest sulla sessione (il
       // client usato piu' di recente ne guida la geometria). Fire-and-forget.
       try {
         require('node:child_process').execFile(defaults.tmuxBin || 'tmux',
           ['set-option', '-t', `=${msg.session}:`, 'window-size', 'latest'], () => {});
       } catch (_) {}
-      pty = openAttach(msg.session, {
+      const takeSize = msg.takeSize !== undefined
+        ? !!msg.takeSize
+        : countClients(msg.session) === 0;
+      record = {
+        pty: openAttach(msg.session, {
         // readonlyDefault del server e' un PAVIMENTO, non un default: se il server
         // e' READONLY nessun client puo' declassarlo (msg.readonly:false non deve
         // vincere). Il client puo' solo AGGIUNGERE restrizione (attach read-only
@@ -80,34 +249,84 @@ function bindWs(ws, deps) {
         cols: clamp(msg.cols, 20, 300, 80),
         rows: clamp(msg.rows, 5, 120, 24),
         tmuxBin: defaults.tmuxBin || 'tmux',
+        }),
+        ws,
+        session: msg.session,
+        readonly: defaults.readonlyDefault === true || !!msg.readonly,
+        takeSize,
+        ended: false,
+        exitCode: undefined,
+        resumeToken: null,
+        graceTimer: null,
+        graceExpired: false,
+      };
+      // The token is issued for this record, not for an arbitrary caller.
+      if (ptyGrace) record.resumeToken = ptyGrace.issueToken(record);
+      onAttach(session, ws);
+      record.pty.onData((d) => {
+        if (!record.ws) return;
+        try { record.ws.send(Buffer.from(d), { binary: true }); } catch (_) { return; }
+        if ((record.ws.bufferedAmount || 0) > MAX_BUFFERED) fail(1011, 'backpressure');
       });
-      pty.onData((d) => {
-        try { ws.send(Buffer.from(d), { binary: true }); } catch (_) { return; }
-        if ((ws.bufferedAmount || 0) > MAX_BUFFERED) fail(1011, 'backpressure');
-      });
-      pty.onExit((info) => {
-        try { ws.send(JSON.stringify({ type: 'exit', code: info && info.exitCode })); } catch (_) {}
-        try { ws.close(1000, 'exit'); } catch (_) {}
+      record.pty.onExit((info) => {
+        record.ended = true;
+        record.exitCode = info && info.exitCode;
+        logClose('notice', 'PTY_EXIT', 'Sessione terminata dal PTY', {
+          exitCode: typeof record.exitCode === 'number' ? record.exitCode : undefined,
+        });
+        if (!record.ws) return;
+        sendJson(record.ws, { type: 'exit', code: record.exitCode });
+        try { record.ws.close(1000, 'exit'); } catch (_) {}
       });
+      sendJson(ws, { type: 'attached', reconnectToken: record.resumeToken });
       return;
     }
     // dopo l'attach
-    if (isBinary) { pty.write(data); return; }
+    if (isBinary) { if (!record.readonly) record.pty.write(data); return; }
     let msg;
     try { msg = JSON.parse(data.toString()); } catch (_) { return; }
     if (msg.type === 'attach') return fail(1002, 'already attached'); // no 2nd attach
-    if (msg.type === 'resize') pty.resize(clamp(msg.cols, 20, 300, 80), clamp(msg.rows, 5, 120, 24));
+    if (msg.type === 'resize') record.pty.resize(clamp(msg.cols, 20, 300, 80), clamp(msg.rows, 5, 120, 24));
     // focus: il tile che prende il focus diventa size-owner (promote); perdendolo
     // torna ignore-size (demote). Cosi' N deck/tile sulla stessa sessione NON si
     // contendono la geometria: comanda solo chi ha il focus (§5b size policy).
-    else if (msg.type === 'focus') { if (msg.on) pty.promote(); else pty.demote(); }
-    else if (msg.type === 'input') pty.write(typeof msg.data === 'string' ? msg.data : '');
-    else if (msg.type === 'key') pty.write(typeof msg.seq === 'string' ? msg.seq.slice(0, 64) : '');
+    else if (msg.type === 'focus') { if (msg.on) record.pty.promote(); else record.pty.demote(); }
+    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
   }
 
+  // Alla riconnessione la DURATA della caduta e' il gap close->reopen della
+  // stessa sessione. Ritorni con gap = notice (sempre visibili); un primo
+  // attach senza storia e' debug (solo verbose).
+  function logReattach() {
+    if (!diagnostics) return;
+    if (!dropCounter) return;
+    try {
+      const reopen = dropCounter.recordReopen(session);
+      if (reopen.gapMs != null) {
+        diagnostics.record('notice', 'ws', 'WS_REATTACHED', 'Riconnesso dopo una caduta', {
+          cell: session, gapMs: reopen.gapMs, drops: reopen.drops,
+        });
+      } else {
+        diagnostics.record('debug', 'ws', 'WS_ATTACHED', 'Attach completato', { cell: session });
+      }
+    } catch (_) {}
+  }
+
   ws.on('message', onMessage);
-  ws.on('close', () => { clearAttachTimer(); if (pty) pty.kill(); pty = null; });
-  ws.on('error', () => { clearAttachTimer(); if (pty) pty.kill(); pty = null; });
+  ws.on('close', (code) => {
+    clearAttachTimer(); detach();
+    if (closeLogged) return;
+    const closeCode = Number(code) || undefined;
+    if (ws.__ncCloseReason === 'heartbeat-timeout') {
+      logClose('warn', 'WS_HEARTBEAT_DROPPED', 'Heartbeat scaduto: connessione mezzo-aperta terminata', { closeCode, ...countDrop() });
+    } else if (closeCode === 1006) {
+      logClose('warn', 'WS_ABNORMAL_CLOSE', 'Chiusura senza handshake (drop TCP o terminate)', { closeCode, ...countDrop() });
+    } else {
+      logClose('notice', 'WS_CLIENT_CLOSE', 'Il client ha chiuso la connessione', { closeCode, ...countDrop() });
+    }
+  });
+  ws.on('error', () => { clearAttachTimer(); detach(); });
 }
-module.exports = { bindWs, clamp };
+module.exports = { bindWs, clamp, createPtyGraceStore, PTY_GRACE_MS };

package/lib/ws/drop-counter.js

@@ -0,0 +1,37 @@
+'use strict';
+// Contatore di cadute WebSocket: trasforma «celle che vanno e vengono»
+// in numeri — quante cadute nella finestra (default 10 minuti) e, alla
+// riconnessione, quanto è durata la caduta (gap tra close e reopen).
+// In memoria, zero I/O: i valori viaggiano nei meta dei log di bridge.js.
+function createDropCounter({ windowMs = 10 * 60 * 1000, now = Date.now } = {}) {
+  const drops = []; // { ts, sessionId }
+  const lastClose = new Map(); // sessionId -> ts
+  const key = (s) => String(s == null ? '' : s);
+  function prune(ts) {
+    const cutoff = ts - windowMs;
+    while (drops.length && drops[0].ts < cutoff) drops.shift();
+  }
+  return {
+    recordDrop(session, ts = now()) {
+      const k = key(session);
+      drops.push({ ts, sessionId: k });
+      if (k) lastClose.set(k, ts);
+      prune(ts);
+      return { drops: drops.length, windowSeconds: Math.round(windowMs / 1000) };
+    },
+    // Alla riconnessione: la durata della caduta e' il gap close->reopen.
+    // Consuma il last close: una connessione lunga e sana non e' «ritorno».
+    recordReopen(session, ts = now()) {
+      const k = key(session);
+      const last = lastClose.get(k);
+      lastClose.delete(k);
+      prune(ts);
+      return { gapMs: last == null ? null : Math.max(0, ts - last), drops: drops.length };
+    },
+    snapshot(ts = now()) {
+      prune(ts);
+      return { drops: drops.length, windowSeconds: Math.round(windowMs / 1000) };
+    },
+  };
+}
+module.exports = { createDropCounter };

package/package.json

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

package/skills/nexuscrew/SKILL.md

@@ -23,7 +23,7 @@ Five nouns carry almost everything:
 - **Node** — one installation on one machine. Its identity is an opaque
   `instanceId`; the human-readable name is a **label**, and two nodes may
   legitimately carry the same one. **Address things by id, never by name.**
-- **Cell** — one stable working identity (`Dev`, `Research`, …) bound to one
+- **Cell** — one stable working identity (`Alpha`, `Beta`, …) bound to one
   tmux session and one engine. A cell is not a process: it survives restarts of
   the service, and stopping it does not end the work it was doing.
 - **Engine** — what a cell runs: an AI CLI, a plain shell, a command in a