@mmmbuto/nexuscrew 0.8.52-rc.2 → 0.8.52-rc.21

package/lib/proxy/federation.js

@@ -60,6 +60,22 @@ function classifyShareFailure(health) {
   return { code: 'share-peer-unreachable', detail };
 }
 
+// Porta del canale reverse realmente in gioco, vista DALL'HUB: lo slot attivo
+// del pool quando c'e', altrimenti la `localPort` del peer — che e' il punto
+// su cui l'hub sonda davvero (cfr. nodes test, ramo inbound). NON
+// `reversePort`: quello e' il campo negoziato che vive sul CLIENT, e sull'hub
+// e' assente. Il test del comportamento ha trovato questo scambio; il valore
+// e' il dato che manca per capire un rifiuto, quindi sbagliarlo lo renderebbe
+// peggio che inutile, mandando a cercare sulla porta sbagliata.
+function activeReversePort(peer) {
+  const pool = peer && peer.reversePool;
+  if (pool && Array.isArray(pool.slots)) {
+    const slot = pool.slots[pool.activeSlot];
+    if (slot && Number.isInteger(slot.port)) return slot.port;
+  }
+  return peer && Number.isInteger(peer.localPort) ? peer.localPort : null;
+}
+
 function peerFromToken(nodesPath, token) {
   const st = store.loadStore(nodesPath);
   if (!st || !token) return null;
@@ -111,19 +127,28 @@ function knownResource(resource) {
     //
     // These four were briefly removed on 2026-08-05 over `update_candidate`,
     // which names the URL a device fetches its own update from and accepts
-    // `http:`. The removal was wrong on both counts. It was incoherent: a paired
-    // peer is trusted as its owner (docs/SECURITY.md). And it was ineffective:
-    // `/fleet/define-engine` + `/fleet/up` are federated, so a peer can already
-    // define an arbitrary command and run it on the host — including one that
-    // calls the local `/api/vl-nodes` endpoints. The door was shut next to an
-    // open window.
+    // `http:`. The removal was wrong on two counts, one absolute and one
+    // conditional.
+    //
+    // Incoherent, always: a paired peer is trusted as its owner
+    // (docs/SECURITY.md), and singling out VL nodes made them the only
+    // unfederated resource in their own control plane.
+    //
+    // Ineffective, but ONLY where fleet is available: `/fleet/define-engine` +
+    // `/fleet/define-cell` + `/fleet/up` are federated, and a managed shell
+    // engine with a raw `commands[shell]` resolves to `bash -lic "<raw>"` — so
+    // a peer can already run anything on the host, including a call to these
+    // endpoints locally. VL is orthogonal to fleet: on an owner with VL enabled
+    // and `/fleet/*` unavailable that path does not exist, and federating these
+    // four DOES add capability. It stays within the trust model, so it is not a
+    // violation — but do not repeat "it grants nothing" without that condition.
     //
     // `update_candidate` is still a real defect. It belongs to the command, not
     // to this allowlist: bind the update channel to something the receiving
     // owner controls. Fixing it here only hid it.
     || resource === '/vl-nodes'
     || resource === '/vl-nodes/invite'
-    || /^\/vl-nodes\/[a-f0-9]{32}(?:\/commands)?$/.test(resource)
+    || /^\/vl-nodes\/[a-f0-9]{32}(?:\/commands|\/events)?$/.test(resource)
     || resource === '/decks'
     || /^\/decks\/[a-z0-9-]{1,32}$/.test(resource)
     || resource === '/topology'
@@ -142,6 +167,13 @@ function knownResource(resource) {
     // ADMITS a further node, so leaving it federated would let a peer break the
     // very boundary the owner chose. Minting an invite is done on the hub.
     || resource === '/ws'
+    // Un avviso all'operatore attraversa la federazione con la stessa spina
+    // dorsale dell'audio: origine provata dalla catena `visited`, ACL del
+    // target, budget dedicato. NON e' la coda di NC-NEXT-07 (§5 del modello di
+    // autorita'): quella differisce un'esecuzione, questo mostra del testo e
+    // non esegue nulla. `/audio/speak` esce da un altoparlante in una stanza
+    // fisica ed e' gia' federato: una notifica e' meno invasiva di cosi'.
+    || resource === '/notify'
     || resource === '/audio/capability'
     || resource === '/audio/speak'
     || resource === '/audio/speak/status'
@@ -163,6 +195,10 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/vl-nodes') return method === 'GET';
   if (resource === '/vl-nodes/invite') return method === 'POST';
   if (/^\/vl-nodes\/[a-f0-9]{32}\/commands$/.test(resource)) return method === 'POST';
+  // Sola lettura del ring: la conversazione si vede da qualunque peer
+  // autorizzato, come ogni altra risorsa. GET e basta — questo canale non
+  // deve mai diventare un canale comandi implicito.
+  if (/^\/vl-nodes\/[a-f0-9]{32}\/events$/.test(resource)) return method === 'GET';
   if (/^\/vl-nodes\/[a-f0-9]{32}$/.test(resource)) return method === 'DELETE';
   if (resource === '/decks') return method === 'GET' || method === 'POST';
   if (/^\/decks\/[a-z0-9-]{1,32}$/.test(resource)) {
@@ -175,6 +211,10 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/ws') return method === 'GET';
   if (/^\/fleet\/(status|schema|definitions|credentials\/status)$/.test(resource)) return method === 'GET';
   if (/^\/fleet\/(credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource)) return method === 'POST';
+  // Notify: solo POST. `/events`, `/asks` e `/push/*` restano NON federati —
+  // SSE non puo' autenticarsi col Bearer e un ask ha un canale di ritorno che
+  // e' un paste nel tmux locale, quindi non attraverserebbe comunque.
+  if (resource === '/notify') return method === 'POST';
   // Audio: only capability read, speak and stop are exposed through Hydra.
   // audio.consent is a LOCAL mutation and MUST stay unreachable federated.
   if (resource === '/audio/capability') return method === 'GET';
@@ -793,7 +833,7 @@ async function probeReverseOwner(peer, fetchImpl = fetch) {
   });
 }
 
-function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly = () => false, version = null, roles = null, hopSecret = null }) {
+function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly = () => false, version = null, roles = null, hopSecret = null, diagnostics = null }) {
   const r = express.Router();
   r.use((req, res, next) => {
     const peer = peerFromToken(nodesPath, bearerFrom(req));
@@ -1029,6 +1069,21 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
           // guasto definitivo senza interpretare una stringa. Solo il canale
           // non ancora salito e' ritentabile.
           const failure = classifyShareFailure(health);
+          // L'hub sa di aver rifiutato e sa perche', e finora non lo scriveva
+          // da nessuna parte: l'errore viveva solo nel toast del dispositivo,
+          // che e' l'unico posto dove chi amministra l'hub non puo' guardarlo.
+          // Un rifiuto ripetuto diventava cosi' un mistero — e' costato ore su
+          // un caso reale, risolto solo leggendo i log di sshd con i privilegi
+          // di root. Meta bounded: nome nodo, codice tipizzato, porta tentata.
+          // Nessun testo remoto, nessuna credenziale.
+          if (diagnostics && typeof diagnostics.record === 'function') {
+            diagnostics.record('warn', 'share', 'SHARE_CHANNEL_REFUSED',
+              'Share refused: the reverse channel did not come up', {
+                node: req.peer.name,
+                code: failure.code,
+                port: activeReversePort(req.peer),
+              });
+          }
           return res.status(409).json({
             error: 'canale share non raggiungibile',
             code: failure.code,
@@ -1060,7 +1115,7 @@ function localRouter({ nodesPath, localPort, localCredential, readonly, hopSecre
   return r;
 }
 
-function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredential, ingress, readonly = () => false, activeSockets = null }) {
+function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredential, ingress, readonly = () => false, activeSockets = null, hopSecret = null }) {
   if (readonly()) return reject(socket, 403);
   const parsed = parseRoute(req.url.replace(/^\/(?:api\/route|federation\/route)/, ''));
   if (!parsed || parsed.resource !== '/ws') return reject(socket, 404);
@@ -1079,7 +1134,18 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
   }
   const up = net.connect({ host: '127.0.0.1', port });
   up.once('connect', () => {
-    const headers = cleanHeaders(req.headers, credential, parsed.route.length ? visited : null);
+    // 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
+    // token. La catena PIU' la prova di hop sono cio' che lo distingue —
+    // esattamente come fa routeHandler per il percorso HTTP. Senza, il nodo che
+    // possiede la sessione non sa quale peer stia aprendo il suo PTY, e ogni
+    // permesso per-cella diventa decorativo: `/ws` attacca per NOME di
+    // sessione, quindi basta indovinarlo.
+    const secret = typeof hopSecret === 'function' ? hopSecret() : hopSecret;
+    const hopProof = !parsed.route.length && secret
+      ? signHop(secret, { method: req.method || 'GET', path, visited })
+      : null;
+    const headers = cleanHeaders(req.headers, credential, visited, hopProof);
     const lines = [`GET ${path} HTTP/1.1`, `Host: 127.0.0.1:${port}`];
     for (const [k, v] of Object.entries(headers)) lines.push(`${k}: ${Array.isArray(v) ? v.join(', ') : v}`);
     lines.push('Connection: Upgrade', 'Upgrade: websocket', '', '');
@@ -1097,7 +1163,7 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
 function reject(socket, code) { try { socket.end(`HTTP/1.1 ${code} Error\r\nConnection: close\r\n\r\n`); } catch (_) {} }
 
 module.exports = {
-  MAX_HOPS, ROUTE_DELIMITER, TOPOLOGY_PEER_TIMEOUT_MS, SHARE_NOT_READY_CODE, classifyShareFailure,
+  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,
   probeHealth, waitForHealthyPeer, canListenLoopback, preflightHubReverse, notifyHubShare, reconcilePeerShare, runShareRevokeBoot, probeReverseOwner,

package/lib/server.js

@@ -39,12 +39,20 @@ const { isConsent: isAudioConsent } = require('./audio/consent.js');
 const { createOriginResolver } = require('./audio/origin.js');
 const { createAudioAcl } = require('./audio/acl.js');
 const { createDispatcher } = require('./audio/dispatch.js');
+const { createCellScopeGuard } = require('./cells/scope-guard.js');
+const { createCellScope } = require('./cells/scope.js');
+const { cellIdFromTmuxSession } = require('./fleet/definitions.js');
+// Budget a tre finestre, riusato dalle notifiche federate: e' gia' scritto per
+// limitare il danno di un nodo che mente sulla propria cella (il tetto per
+// target si calcola sul NODO, che la catena visited verifica).
+const { createSpeakRateLimiter } = require('./audio/rate-limit.js');
 const { createSpeakQueue } = require('./audio/queue.js');
 const { createReceiptStore } = require('./audio/receipt.js');
 const audioAdapters = require('./audio/adapters.js');
 const audioGroups = require('./audio/groups.js');
 const { bridgeSecretPath, loadOrCreateBridgeSecret, createNonceCache } = require('./audio/bridge-auth.js');
-const { createHopSecret } = require('./proxy/hop-proof.js');
+const { createHopSecret, verifyHop, HOP_HEADER } = require('./proxy/hop-proof.js');
+const { parseVisitedChain } = require('./audio/origin.js');
 const { settingsRoutes, publicPeeringRoutes } = require('./settings/routes.js');
 const decksStore = require('./decks/store.js');
 const { decksRoutes } = require('./decks/routes.js');
@@ -105,6 +113,10 @@ function createServer(opts = {}) {
   // alla porta sbagliata (bug reale: 401/"unauthorized" dal servizio su cfg.port).
   let server = null;
   const previews = createPreviewSampler(cfg.tmuxBin);
+  // Seam di test per l'esistenza di una sessione: senza, un test sullo scope
+  // dell'attach non discrimina, perche' ogni sessione risulta assente e il
+  // rifiuto arriverebbe comunque — un verde che non prova nulla.
+  const sessionExistsImpl = cfg.sessionExistsSeam || ((name) => sessionExists(cfg.tmuxBin, name));
   // MCP bridge (notify/ask/push): lo stato vive accanto al token (dirname del
   // tokenPath = ~/.nexuscrew di default) cosi' le istanze isolate via opts/env
   // nei test NON scrivono mai nella home reale. Tutto lazy: vapid.json/asks.json
@@ -541,6 +553,51 @@ function createServer(opts = {}) {
   // ma il token chiude anche altri processi locali della stessa macchina.
   const api = express.Router();
   api.use(requireToken(tokenStore));
+  // Origine per lo scope celle: stessa prova di hop usata da audio e notify.
+  // requireCell:false perche' qui interessa QUALE NODO parla, non quale cella
+  // dichiari — la cella e' solo attestata e non deve decidere un permesso.
+  const cellScopeOrigin = createOriginResolver({
+    localNodeId: () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null,
+    hopSecret: () => hopSecret,
+  });
+  const cellScoper = createCellScope({
+    nodesPath,
+    cellForSession: (session) => cellIdFromTmuxSession(session),
+  });
+  // Variante SINCRONA per l'upgrade WebSocket: verifica la prova di hop e la
+  // catena senza passare dal resolver async. Un upgrade non federato — o con
+  // una prova che non regge — resta senza restrizioni, esattamente come una
+  // richiesta locale: la prova la costruisce il proxy, un peer non puo' ne'
+  // toglierla ne' falsificarla.
+  const wsCellScope = (req) => {
+    try {
+      const headers = (req && req.headers) || {};
+      const proof = headers[HOP_HEADER];
+      if (!proof) return cellScoper.resolve({ trust: 'local-bridge' });
+      const self = (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
+      const visited = parseVisitedChain(headers['x-nexuscrew-visited'], self);
+      if (!visited) return cellScoper.resolve({ trust: 'federated', visited: [] });
+      const ok = verifyHop(hopSecret, {
+        method: req.method || 'GET', path: '/ws', visited,
+      }, proof);
+      if (!ok) return cellScoper.resolve({ trust: 'federated', visited: [] });
+      return cellScoper.resolve({ trust: 'federated', visited });
+    } catch (_) {
+      // Fail-closed: se non si riesce a stabilire l'origine, nessuna sessione.
+      return cellScoper.resolve({ trust: 'federated', visited: [] });
+    }
+  };
+  // Scope celle (NC-E): un punto solo decide cosa un peer federato vede e puo'
+  // toccare. Sta qui, prima di ogni route, perche' i canali da cui una cella
+  // trapela sono molti e crescono: filtrarli uno per uno significa dimenticarne
+  // uno, e un permesso che vale su quasi tutti i canali non e' un permesso.
+  // Le richieste locali non lo attraversano: il proprietario della macchina non
+  // si limita da solo.
+  api.use(createCellScopeGuard({
+    nodesPath,
+    cellForSession: (session) => cellIdFromTmuxSession(session),
+    resolveOrigin: (req) => cellScopeOrigin.resolve(req, { requireCell: false }),
+  }));
   api.get('/sessions', async (_req, res) => {
     try {
       const sessions = await listSessions(cfg.tmuxBin);
@@ -615,6 +672,19 @@ function createServer(opts = {}) {
   }));
   // MCP bridge (design §2): /notify, /push/*, /asks — dietro lo stesso Bearer
   // del router /api; gate READONLY sui mutanti dentro notifyRoutes.
+  // Identita' e instradamento condivisi con l'audio: stessa fonte (node store),
+  // stesso segreto di hop, stessa inventory. Due modelli di provenienza
+  // divergenti sarebbero un bug latente.
+  const federatedNodeId = () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
+  const federatedPeers = async () => {
+    const st = nodesStore.loadStore(nodesPath);
+    if (!st) return [];
+    const topology = await federation.collectLocalTopology({ nodesPath, cachePath: topologyCachePath, fetchImpl: healthFetch });
+    return nodesInventory.buildInventory({
+      direct: nodesStore.redactStore(st).nodes,
+      topology: topology && Array.isArray(topology.nodes) ? topology.nodes : [],
+    });
+  };
   api.use(notifyRoutes({
     cfg,
     notifier,
@@ -622,6 +692,22 @@ function createServer(opts = {}) {
     asks: asksStore,
     paste: (session, text) => pasteToSession(cfg.tmuxBin, session, text),
     sessionExists: (name) => sessionExists(cfg.tmuxBin, name),
+    localNodeId: federatedNodeId,
+    // requireCell resta true: una notifica federata porta sempre una cella
+    // attestata, che serve ad attribuirla e a calcolarne il budget.
+    originResolver: createOriginResolver({
+      localNodeId: federatedNodeId,
+      hopSecret: () => hopSecret,
+    }),
+    acl: createAudioAcl({ nodesPath }),
+    dispatcher: createDispatcher({
+      localNodeId: federatedNodeId,
+      peers: federatedPeers,
+      localPort: () => (server && server.address() ? server.address().port : cfg.port),
+      localToken: () => tokenHolder.value,
+      statuses: new Set(['delivered', 'refused', 'unreachable', 'unknown']),
+    }),
+    federatedRate: createSpeakRateLimiter(),
   }));
   api.use('/fleet', fleetRoutes(fleetP, { ...cfg, diagnostics }));
   // Audio Share. L'identita' del nodo NON e' un campo di cfg: si legge dal node
@@ -787,6 +873,7 @@ function createServer(opts = {}) {
     nodesPath, localPort: () => (server && server.address() ? server.address().port : cfg.port), localCredential: () => tokenHolder.value, readonly: proxyReadonly, version: VERSION,
     fetchImpl: healthFetch, hopSecret: () => hopSecret,
     roles: () => require('./cli/commands.js').readRoles(cfg.configPath || configJsonPath()),
+    diagnostics,
   }));
 
   // Reverse-proxy single-origin /node/<name>/… (design §4b(2)). Auth locale PRIMA
@@ -868,13 +955,13 @@ function createServer(opts = {}) {
       let u; try { u = new URL(req.url, 'http://127.0.0.1'); } catch (_) { return socket.destroy(); }
       const given = bearerFrom(req) || u.searchParams.get('token') || '';
       if (!verify(tokenHolder.value, given)) return socket.destroy();
-      federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: runtimePort, localCredential: () => tokenHolder.value, ingress: null, readonly: proxyReadonly, activeSockets: proxySockets });
+      federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: runtimePort, localCredential: () => tokenHolder.value, ingress: null, readonly: proxyReadonly, activeSockets: proxySockets, hopSecret: () => hopSecret });
       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 });
+      federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: runtimePort, localCredential: () => tokenHolder.value, ingress, readonly: proxyReadonly, activeSockets: proxySockets, hopSecret: () => hopSecret });
       return;
     }
     if (pathname === '/node' || pathname.startsWith('/node/')) {
@@ -900,10 +987,19 @@ function createServer(opts = {}) {
     // non possono settare header sui WS -> il flusso locale resta identico
     // (token nel frame attach, mai in URL).
     const preauth = req ? verify(tokenHolder.value, bearerFrom(req)) : false;
+    // Scope celle sull'ATTACH. Calcolato in modo sincrono di proposito: rendere
+    // async questo handler rischierebbe di perdere i frame che arrivano prima
+    // di bindWs. `/ws` attacca per NOME DI SESSIONE e senza questo gate ogni
+    // filtro sugli elenchi sarebbe decorativo — basterebbe indovinare
+    // `cloud-Dev`.
+    const wsScope = wsCellScope(req);
     bindWs(ws, {
       openAttach,
       verifyToken: (t) => preauth || verify(tokenHolder.value, t),
-      isValidSession: (name) => sessionExists(cfg.tmuxBin, name),
+      // Una sessione fuori scope viene trattata come inesistente: il client
+      // riceve 4404, lo stesso codice di una sessione che non c'e'. Dire "esiste
+      // ma non puoi" rivelerebbe proprio cio' che lo scope nasconde.
+      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 },

package/lib/settings/routes.js

@@ -72,7 +72,7 @@ const { publicPeeringRoutes } = require('./public-peering-routes.js');
 const CONFIG_KEYS = new Set(['roles', 'port', 'wizardDone', 'autoUpdate', 'alternateScreen']);
 const ROLE_KEYS = new Set(['client', 'node']);
 const ADD_KEYS = new Set(['name', 'ssh', 'sshPort', 'remotePort', 'localPort', 'keyPath', 'label']);
-const EDIT_KEYS = new Set(['label', 'ssh', 'sshPort', 'autostart', 'visibility', 'selected']);
+const EDIT_KEYS = new Set(['label', 'ssh', 'sshPort', 'autostart', 'visibility', 'selected', 'cellVisibility', 'cells']);
 const LOCAL_AUDIO_TEST_TEXT = 'NexusCrew audio test.';
 
 // Default sensato per il "nome dispositivo" proposto nei form (pairing/invite).

package/lib/vl-nodes/broker.js

@@ -39,6 +39,98 @@ function sanitizeHealth(raw) {
   };
 }
 
+// --- eventi di sessione (passo 2) ------------------------------------------
+// I kind ammessi sono una WHITELIST, non una blacklist: un kind sconosciuto
+// cade fuori da solo. `tool_args` e `tool_result` non sono nell'elenco per una
+// ragione precisa — contengono file, output di comandi e potenziali segreti, e
+// viaggeranno solo su richiesta esplicita (passo 3). Non troncarli: escluderli.
+const EVENT_KINDS = new Set([
+  'text', 'thinking', 'tool_start', 'tool_end', 'usage',
+  'turn_end', 'done', 'error', 'gap', 'truncate', 'writer_epoch',
+]);
+// Questi non si perdono mai: senza di loro la UI mostra un turno che non
+// finisce, indistinguibile da un nodo bloccato.
+const TERMINAL_KINDS = new Set(['turn_end', 'done', 'error']);
+// 16 KiB e non 64: il poll e' montato con express.json({ limit: '20kb' }) e
+// oltre quel tetto la route risponde 413, cioe' il device si scollega.
+const MAX_EVENTS_BYTES = 16_384;
+const MAX_EVENT_TEXT = 4_096;
+// Il ring vive in memoria e si perde al restart: la copia durevole e' il
+// journal sul device. L'hub non accumula la conversazione nel tempo, e non la
+// scrive su disco: la visibilita' e' viva, non e' un archivio.
+const RING_MAX_EVENTS = 512;
+const RING_MAX_BYTES = 262_144;
+
+function sanitizeEvent(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (!Number.isSafeInteger(raw.seq) || raw.seq < 0) return null;
+  const kind = typeof raw.kind === 'string' ? raw.kind : '';
+  if (!EVENT_KINDS.has(kind)) return null;
+  const event = { seq: raw.seq, kind };
+  const at = boundedInteger(raw.at, 0, Number.MAX_SAFE_INTEGER);
+  if (at) event.at = at;
+  const text = boundedString(raw.text, MAX_EVENT_TEXT);
+  if (text) event.text = text;
+  const name = boundedString(raw.name, 128);
+  if (name) event.name = name;
+  if (raw.isError === true) event.isError = true;
+  const count = boundedInteger(raw.count, 0, Number.MAX_SAFE_INTEGER);
+  if (count) event.count = count;
+  return event;
+}
+
+function sanitizeEvents(raw) {
+  if (!Array.isArray(raw)) return { events: [], dropped: 0 };
+  const clean = [];
+  for (const item of raw.slice(0, RING_MAX_EVENTS * 2)) {
+    const event = sanitizeEvent(item);
+    if (event) clean.push(event);
+  }
+  clean.sort((a, b) => a.seq - b.seq);
+
+  // I terminali sono messi da parte PRIMA di spendere il budget, cosi' un
+  // overflow di testo non puo' mangiarseli.
+  const terminals = clean.filter((e) => TERMINAL_KINDS.has(e.kind));
+  const rest = clean.filter((e) => !TERMINAL_KINDS.has(e.kind));
+  const reserve = JSON.stringify(terminals).length + 64;
+  const budget = MAX_EVENTS_BYTES - reserve;
+
+  const kept = [];
+  let used = 2;
+  let dropped = 0;
+  let firstDroppedSeq = 0;
+  for (const event of rest) {
+    const size = JSON.stringify(event).length + 1;
+    if (used + size <= budget) {
+      kept.push(event);
+      used += size;
+    } else {
+      dropped += 1;
+      if (!firstDroppedSeq) firstDroppedSeq = event.seq;
+    }
+  }
+
+  const events = kept.concat(terminals);
+  // Lo scarto e' SEMPRE dichiarato: un buco silenzioso in UI si legge come
+  // "non e' successo niente", che e' peggio del buco.
+  if (dropped > 0) events.push({ seq: firstDroppedSeq, kind: 'gap', count: dropped });
+  events.sort((a, b) => a.seq - b.seq);
+  return { events, dropped };
+}
+
+// La sessione VL dichiarata dal nodo (sidebar: «N900 · 1 sessione»). Solo
+// attach + label del profilo, mai contenuto: qualunque campo extra viene
+// potato, non troncato — stessa disciplina della whitelist eventi. Assente o
+// invalida -> null: un binario piu' vecchio non dichiara sessioni che non ha
+// e non sparisce dalla lista.
+function sanitizeSession(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (raw.attached !== true && raw.attached !== false) return null;
+  const profile = boundedString(raw.profile, 64);
+  if (!profile) return null;
+  return { attached: raw.attached, profile };
+}
+
 function sanitizeHeartbeat(raw) {
   if (!raw || raw.protocol !== PROTOCOL || !SESSION_RE.test(String(raw.sessionId || ''))
     || !Number.isSafeInteger(raw.seq) || raw.seq < 0) return null;
@@ -53,6 +145,7 @@ function sanitizeHeartbeat(raw) {
     capabilities,
     health: sanitizeHealth(raw.health),
     ack: sanitizeAck(raw.ack),
+    session: sanitizeSession(raw.session),
   };
 }
 
@@ -76,6 +169,9 @@ function createBroker(options = {}) {
         waiter: null,
         inflight: null,
         lastAck: null,
+        events: [],
+        eventsCursor: 0,
+        eventsBytes: 0,
       };
       states.set(node.nodeId, state);
     }
@@ -94,6 +190,34 @@ function createBroker(options = {}) {
     return true;
   }
 
+  // At-least-once: il device rimanda dall'ultimo cursore confermato, quindi
+  // rivedere un seq gia' accettato e' normale, non un errore. Il dedup e' qui.
+  function ingestEvents(state, raw) {
+    const incoming = sanitizeEvents(raw);
+    if (!incoming.events.length) return;
+    for (const event of incoming.events) {
+      if (event.seq <= state.eventsCursor) continue;
+      state.events.push(event);
+      state.eventsBytes += JSON.stringify(event).length;
+      state.eventsCursor = event.seq;
+    }
+    while (state.events.length > RING_MAX_EVENTS || state.eventsBytes > RING_MAX_BYTES) {
+      const evicted = state.events.shift();
+      if (!evicted) break;
+      state.eventsBytes -= JSON.stringify(evicted).length;
+    }
+  }
+
+  function events(nodeId, { after = 0 } = {}) {
+    const state = states.get(nodeId);
+    if (!state) return { events: [], cursor: 0 };
+    const from = Number.isSafeInteger(after) && after > 0 ? after : 0;
+    return {
+      events: from ? state.events.filter((e) => e.seq > from) : state.events.slice(),
+      cursor: state.eventsCursor,
+    };
+  }
+
   function observe(node, raw) {
     const heartbeat = sanitizeHeartbeat(raw);
     if (!heartbeat) return { ok: false, code: 'invalid-heartbeat' };
@@ -120,6 +244,7 @@ function createBroker(options = {}) {
     }
     state.lastSeen = now();
     state.heartbeat = heartbeat;
+    ingestEvents(state, raw && raw.events);
     let acknowledged = false;
     if (heartbeat.ack && state.inflight && heartbeat.ack.id === state.inflight.id) {
       state.lastAck = { ...heartbeat.ack, at: state.lastSeen };
@@ -146,7 +271,9 @@ function createBroker(options = {}) {
     const state = observed.state;
     finishWaiter(state, { type: 'superseded', generation: state.generation });
     if (observed.acknowledged) {
-      return Promise.resolve({ type: 'acknowledged', generation: state.generation });
+      return Promise.resolve({
+        type: 'acknowledged', generation: state.generation, eventsCursor: state.eventsCursor,
+      });
     }
     const boundedWait = Math.max(1, Math.min(MAX_WAIT_MS, Number(waitMs) || MAX_WAIT_MS));
     return new Promise((resolve) => {
@@ -167,7 +294,9 @@ function createBroker(options = {}) {
         waiter.cleanup = () => signal.removeEventListener('abort', onAbort);
       }
       state.waiter = waiter;
-    });
+      // Il cursore viaggia su OGNI risposta, anche su un poll scaduto a vuoto:
+      // e' cosi' che il device sa quando puo' liberare il proprio buffer.
+    }).then((value) => ({ ...value, eventsCursor: state.eventsCursor }));
   }
 
   function dispatch(nodeId, command) {
@@ -207,13 +336,14 @@ function createBroker(options = {}) {
         version: state?.heartbeat?.version || '',
         capabilities: state?.heartbeat?.capabilities || [],
         health: state?.heartbeat?.health || null,
+        session: state?.heartbeat?.session ?? null,
         inflight: state?.inflight || null,
         lastAck: state?.lastAck || null,
       };
     });
   }
 
-  return { poll, dispatch, forget, list, observe, _states: states };
+  return { poll, dispatch, forget, list, observe, events, _states: states };
 }
 
 module.exports = {
@@ -224,5 +354,12 @@ module.exports = {
   sanitizeHeartbeat,
   sanitizeHealth,
   sanitizeAck,
+  sanitizeSession,
+  sanitizeEvents,
+  EVENT_KINDS,
+  TERMINAL_KINDS,
+  MAX_EVENTS_BYTES,
+  RING_MAX_EVENTS,
+  RING_MAX_BYTES,
   createBroker,
 };

package/lib/vl-nodes/routes.js

@@ -10,6 +10,10 @@ const SIMPLE_COMMANDS = new Set([
   'status', 'health', 'start', 'stop', 'restart', 'version', 'capabilities', 'unpair',
 ]);
 const MAX_CANDIDATE_BYTES = 2_621_440;
+/// Stesso tetto dichiarato dal device (`MAX_PROMPT_TEXT` in protocol.rs): due
+/// numeri diversi qui e la' vorrebbero dire consegnare comandi che il nodo
+/// rifiuta.
+const MAX_PROMPT_TEXT = 4 * 1024;
 
 function commandOf(body) {
   if (!body || typeof body.kind !== 'string') return null;
@@ -18,6 +22,18 @@ function commandOf(body) {
       || Array.isArray(body.args) || Object.keys(body.args).length > 0)) return null;
     return { kind: body.kind, args: {} };
   }
+  // L'unico verbo che porta testo dell'utente fino alla sessione del device.
+  // Il tetto e' lo stesso che il nodo dichiara (4 KiB): rifiutare QUI cio' che
+  // il device rifiuterebbe comunque evita un comando in volo destinato a
+  // fallire, e un `submitted` che l'operatore leggerebbe come «e' partito».
+  if (body.kind === 'prompt') {
+    const args = body.args;
+    if (!args || typeof args !== 'object' || Array.isArray(args)) return null;
+    if (Object.keys(args).join(',') !== 'text') return null;
+    if (typeof args.text !== 'string') return null;
+    if (args.text.length < 1 || Buffer.byteLength(args.text, 'utf8') > MAX_PROMPT_TEXT) return null;
+    return { kind: 'prompt', args: { text: args.text } };
+  }
   if (body.kind === 'logs') {
     const limit = body.args && body.args.limit;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) return null;
@@ -96,6 +112,13 @@ function publicRoutes({ storePath, broker, ownerId }) {
       signal: abort.signal,
     });
     if (res.headersSent || res.destroyed) return undefined;
+    // Il cursore degli eventi viaggia in un HEADER, non nel corpo: la risposta
+    // a un poll scaduto e' un 204 senza corpo, e senza header il device non
+    // saprebbe mai fin dove sono stati accettati i suoi eventi — continuerebbe
+    // a rimandarli. L'header sta su OGNI risposta, anche su quelle vuote.
+    if (Number.isSafeInteger(result.eventsCursor)) {
+      res.set('x-vl-events-cursor', String(result.eventsCursor));
+    }
     if (result.type === 'command') return res.json({ protocol: PROTOCOL, command: result.command });
     if (result.type === 'idle' || result.type === 'aborted' || result.type === 'acknowledged') {
       return res.status(204).end();
@@ -138,6 +161,21 @@ function apiRoutes({ storePath, broker, ownerId, readonly = () => false }) {
     return res.json({ instanceId: localOwner, protocol: PROTOCOL, nodes });
   });
 
+  // Lettura pura del ring in memoria: nessun gate READONLY, perche' non muta
+  // nulla. `after` e' il cursore della UI, cosi' non riscarica tutto a ogni
+  // giro. Cio' che non c'e' piu' nel ring non si recupera da qui: la copia
+  // durevole e' il journal sul device (contratto passo 2, punto 5).
+  r.get('/:nodeId/events', (req, res) => {
+    if (!store.NODE_ID_RE.test(String(req.params.nodeId || ''))
+      || !store.listNodes(storePath).some((node) => node.nodeId === req.params.nodeId)) {
+      return res.status(404).json({ error: 'node not paired' });
+    }
+    const rawAfter = req.query.after === undefined ? 0 : Number(req.query.after);
+    const after = Number.isSafeInteger(rawAfter) && rawAfter > 0 ? rawAfter : 0;
+    const out = broker.events(req.params.nodeId, { after });
+    return res.json({ protocol: PROTOCOL, nodeId: req.params.nodeId, ...out });
+  });
+
   r.post('/invite', express.json({ limit: '4kb' }), (req, res) => {
     if (readonly()) return res.status(403).json({ error: 'READONLY: invite blocked' });
     const localOwner = ownerId();

package/package.json

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