npm - @mmmbuto/nexuscrew - Versions diffs - 0.8.47 → 0.8.49 - Mend

@mmmbuto/nexuscrew 0.8.47 → 0.8.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/CHANGELOG.md +80 -0
package/frontend/dist/assets/{index-BAq6N1Md.css → index-43DFO1EH.css} +1 -1
package/frontend/dist/assets/index-BZ1dY5k6.js +93 -0
package/frontend/dist/index.html +2 -2
package/frontend/dist/version.json +1 -1
package/lib/cells/routes.js +18 -1
package/lib/fleet/builtin.js +7 -1
package/lib/fleet/definitions.js +16 -0
package/lib/fleet/runtime.js +3 -1
package/lib/mcp/cells.js +11 -0
package/lib/mcp/tools.js +1 -1
package/lib/nodes/inventory.js +5 -0
package/lib/nodes/reverse-rotation.js +22 -1
package/lib/nodes/reverse-slot-listeners.js +10 -1
package/lib/nodes/reverse-slot-proof.js +10 -0
package/lib/nodes/topology-cache.js +11 -2
package/lib/proxy/federation.js +98 -10
package/lib/server.js +39 -8
package/lib/settings/routes.js +58 -5
package/lib/ws/bridge.js +26 -2
package/package.json +1 -1
package/frontend/dist/assets/index-Db2ivuxA.js +0 -93

package/frontend/dist/index.html CHANGED Viewed

@@ -11,8 +11,8 @@
   <meta name="apple-mobile-web-app-title" content="NexusCrew" />
   <link rel="manifest" href="/manifest.json" />
   <title>NexusCrew</title>
-  <script type="module" crossorigin src="/assets/index-Db2ivuxA.js"></script>
-  <link rel="stylesheet" crossorigin href="/assets/index-BAq6N1Md.css">
+  <script type="module" crossorigin src="/assets/index-BZ1dY5k6.js"></script>
+  <link rel="stylesheet" crossorigin href="/assets/index-43DFO1EH.css">
 </head>
 <body>
   <div id="root"></div>

package/frontend/dist/version.json CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":"0.8.47"}
1	+ {"version":"0.8.49"}

package/lib/cells/routes.js CHANGED Viewed

@@ -5,6 +5,19 @@ const { isValidSession } = require('../files/store.js');
 const { submitTextOk } = require('../tmux/actions.js');
 const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
+const CELL_LABEL_MAX = 64;
+// Una label che esce da questo nodo, o che arriva da un altro, e' testo
+// AUTO-DICHIARATO: la definizione locale e' gia' validata dal parser, ma il
+// payload che si espone e quello che si riceve vanno delimitati comunque.
+// Senza questo un peer puo' far attraversare la directory a una stringa lunga
+// e con a capo, che ogni consumatore poi renderizza.
+function safeCellLabel(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > CELL_LABEL_MAX) return '';
+  return /[\x00-\x1f\x7f]/.test(trimmed) ? '' : trimmed;
+}
 const NODE_ID_RE = /^[a-f0-9]{16,64}$/;
 const MESSAGE_ID_RE = /^[a-f0-9-]{16,64}$/;
@@ -24,6 +37,10 @@ function publicCells(status, instanceId, now = Date.now()) {
       id: `${instanceId}:${raw.cell}`,
       instanceId,
       cell: raw.cell,
+      // Il nome leggibile viaggia accanto all'id, mai al suo posto: chi riceve
+      // questa voce deve poter capire che ruolo occupa la cella senza dover
+      // interpretare un identificatore scelto da un altro nodo.
+      label: safeCellLabel(raw.label),
       tmuxSession: raw.tmuxSession,
       engine: typeof raw.engine === 'string' ? raw.engine : '',
       model: typeof raw.model === 'string' ? raw.model : '',
@@ -135,4 +152,4 @@ function cellsRoutes({ fleetP, instanceId, submit, readonly = () => false, now =
   return r;
 }
-module.exports = { cellsRoutes, publicCells, parseVisited, validIdentity };
+module.exports = { cellsRoutes, publicCells, parseVisited, validIdentity, safeCellLabel };

package/lib/fleet/builtin.js CHANGED Viewed

@@ -507,7 +507,10 @@ async function createBuiltinFleet(cfg = {}) {
     if (!Array.isArray(cells) || cells.length < 1 || cells.length > MAX_CELLS) {
       throw httpError(400, `cells deve contenere 1..${MAX_CELLS} definizioni`);
     }
-    const allowed = new Set(['id', 'cwd', 'cwdRel', 'engine', 'boot', 'model', 'models', 'permissionPolicies', 'commands', 'prompt']);
+    // `label` e' parte della definizione quanto `prompt`: senza di essa qui, un
+    // backup che la contiene verrebbe rifiutato in restore e il round-trip si
+    // spezzerebbe proprio sulle celle a cui e' stato dato un nome.
+    const allowed = new Set(['id', 'cwd', 'cwdRel', 'engine', 'boot', 'model', 'models', 'permissionPolicies', 'commands', 'prompt', 'label']);
     const seen = new Set();
     for (const cell of cells) {
       if (!cell || typeof cell !== 'object' || Array.isArray(cell)) throw httpError(400, 'definizione cell non valida');
@@ -864,6 +867,9 @@ async function createBuiltinFleet(cfg = {}) {
         permissionPolicies: { type: 'object', required: false, keyRef: 'engine.id', valueEnum: ['standard', 'unsafe'] },
         commands: { type: 'object', required: false, keyRef: 'engine.id', valueMax: CAPS.MAX_CELL_COMMAND_LEN, managedClient: 'shell' },
         prompt: { type: 'string', required: false, max: CAPS.MAX_PROMPT_LEN },
+        // Nome leggibile, distinto dall'id: quest'ultimo resta la chiave di
+        // indirizzamento e l'unica origine della sessione tmux.
+        label: { type: 'string', required: false, max: CAPS.MAX_LABEL_LEN },
       },
     };
   }

package/lib/fleet/definitions.js CHANGED Viewed

@@ -378,6 +378,21 @@ function parseCell(c, engineIds, engineMap = new Map(), { allowLegacyTmuxNames =
     prompt = c.prompt;
   }
+  // label (opzionale): nome LEGGIBILE della cella, distinto dall'id.
+  // L'id resta la chiave stabile con cui si indirizza una cella e con cui si
+  // deriva la sessione tmux; la label e' solo cio' che un umano legge. Senza
+  // questa distinzione l'id fa anche da nome, e un nodo che battezza la propria
+  // cella come il motore la espone cosi' a tutta la rete: chi la riceve non ha
+  // modo di sapere che ruolo occupa. Stessa regola gia' usata per la label
+  // degli engine e per quella dei nodi: stampabile, non vuota, max 64.
+  let label;
+  if (c.label !== undefined) {
+    if (typeof c.label !== 'string') return null;
+    const trimmed = c.label.trim();
+    if (!trimmed || trimmed.length > MAX_LABEL_LEN || !isPrintable(trimmed)) return null;
+    label = trimmed;
+  }
   // tmuxSession: campo esplicito o derivato da id. UNIVOCO (check in caller).
   // Il nome CANONICO e' tmux-safe (v2 per id puntati): tmux normalizza '.' in
   // '_' nei nomi sessione, per cui `cloud-agy.native` diverrebbe `cloud-agy_native`
@@ -422,6 +437,7 @@ function parseCell(c, engineIds, engineMap = new Map(), { allowLegacyTmuxNames =
   if (permissionPolicies) out.permissionPolicies = permissionPolicies;
   if (commands && Object.keys(commands).length) out.commands = commands;
   if (prompt !== undefined) out.prompt = prompt;
+  if (label !== undefined) out.label = label;
   if (legacyTmuxSession) {
     Object.defineProperty(out, 'legacyTmuxSession', {
       value: legacyTmuxSession, enumerable: false, configurable: false,

package/lib/fleet/runtime.js CHANGED Viewed

@@ -93,7 +93,9 @@ function createBuiltinRuntime(ctx) {
         ? 'standard'
         : (remembered || engineDefault || '');
       return {
-        cell: c.id, tmuxSession: c.tmuxSession, engine: c.engine,
+        // `cell` resta l'id: e' la chiave di indirizzamento. `label` e' il nome
+        // leggibile e viaggia accanto, senza mai sostituirlo.
+        cell: c.id, label: c.label || '', tmuxSession: c.tmuxSession, engine: c.engine,
         model: c.model || '', models: { ...(c.models || {}) },
         permissionPolicy: effectivePolicy,
         permissionPolicies: { ...(c.permissionPolicies || {}) },

package/lib/mcp/cells.js CHANGED Viewed

@@ -8,6 +8,9 @@
 // l'astrazione `ctx.api` (loopback + Bearer del bridge); ACL e identita'
 // owner-qualified sono applicate lato server HTTP.
 const { isValidSession } = require('../files/store.js');
+// Stesso validatore usato in uscita: una label federata non deve poter entrare
+// qui in una forma che noi non produrremmo mai.
+const { safeCellLabel } = require('../cells/routes.js');
 const NODE_PART_RE = /^[a-z0-9-]{1,32}$/;
 const NODE_ID_RE = /^[a-f0-9]{16,64}$/;
@@ -109,6 +112,14 @@ function normalizeCellPayload(payload, owner, callerSession = null) {
       owner: owner.label,
       route,
       cell: raw.cell,
+      // `cell` indirizza, `label` si legge. Un nodo che chiama la propria cella
+      // come il motore la esporrebbe cosi' a tutta la rete: senza un nome
+      // separato chi la riceve non ha modo di sapere che ruolo occupa.
+      // La label di una cella REMOTA e' testo auto-dichiarato: si delimita con
+      // lo stesso validatore usato in uscita, e si marca come riferita perche'
+      // chi legge distingua cio' che sappiamo da cio' che ci e' stato detto.
+      label: safeCellLabel(raw.label),
+      labelReported: owner.route.length > 0,
       tmuxSession: raw.tmuxSession,
       engine: typeof raw.engine === 'string' ? raw.engine : '',
       model: typeof raw.model === 'string' ? raw.model : '',

package/lib/mcp/tools.js CHANGED Viewed

@@ -260,7 +260,7 @@ const TOOLS = [
         if (f && f.available) {
           fleet = {
             cells: (Array.isArray(f.cells) ? f.cells : []).map((c) => ({
-              cell: c.cell, session: c.tmuxSession, engine: c.engine, active: !!c.active,
+              cell: c.cell, label: c.label || '', session: c.tmuxSession, engine: c.engine, active: !!c.active,
             })),
           };
         }

package/lib/nodes/inventory.js CHANGED Viewed

@@ -42,6 +42,11 @@ function routedPeer(entry) {
   const route = Array.isArray(entry.route) ? [...entry.route] : [];
   return {
     name: entry.name,
+    // Riferita dal nodo che ce l'ha inoltrata, non verificata da noi: si mostra
+    // perche' senza di essa un nodo in transito e' solo uno slug, ma resta un
+    // dato di seconda mano e non sostituisce l'instanceId.
+    label: typeof entry.label === 'string' ? entry.label : '',
+    labelReported: true,
     nodeId: entry.instanceId,
     instanceId: entry.instanceId,
     kind: 'transitive',

package/lib/nodes/reverse-rotation.js CHANGED Viewed

@@ -75,4 +75,25 @@ function quarantineSlot(pool, { slot, now = Date.now() } = {}) {
   return next;
 }
-module.exports = { LEASE_MS, GRACE_MS, nextReadySlot, prepareRotation, abortPrepared, commitRotation, settleGrace, quarantineSlot };
+// Esito di uno spegnimento che puo' riguardare PIU' entry insieme: durante la
+// grace di una rotazione lo slot vecchio e quello nuovo coesistono. Una
+// chiusura riuscita su una sola non e' una chiusura: dichiararla tale
+// lascerebbe l'altra viva mentre chi chiama registra il canale come privato.
+// `no pidfile` e `stale (pid dead)` contano come spente: li' non e' rimasto
+// nulla di vivo da attribuire.
+const STOP_ALREADY_GONE = ['no pidfile', 'stale (pid dead)'];
+function stopWasDemonstrated(result) {
+  if (!result) return false;
+  return result.stopped === true || STOP_ALREADY_GONE.includes(result.reason);
+}
+function summarizeStops(results) {
+  const list = Array.isArray(results) ? results : [];
+  const stoppedAny = list.some(stopWasDemonstrated);
+  const quarantinedAny = list.some((result) => !stopWasDemonstrated(result));
+  return { stoppedAny, quarantinedAny, allClosed: stoppedAny && !quarantinedAny };
+}
+module.exports = { LEASE_MS, GRACE_MS, nextReadySlot, prepareRotation, abortPrepared, commitRotation, settleGrace, quarantineSlot, stopWasDemonstrated, summarizeStops };

package/lib/nodes/reverse-slot-listeners.js CHANGED Viewed

@@ -23,8 +23,16 @@ function close(server) {
   });
 }
-function createReverseSlotListeners({ app, createServerImpl = http.createServer, diagnostics } = {}) {
+function createReverseSlotListeners({ app, createServerImpl = http.createServer, diagnostics, attachUpgrade } = {}) {
   if (typeof app !== 'function') throw new Error('reverse slot listeners richiede app HTTP');
+  // Fail-closed: servire `app` non basta: il routing degli upgrade WS vive
+  // sull'istanza `server`, non sull'app Express. Un listener senza handler di
+  // upgrade e' HTTP-only e degrada in silenzio (la SPA risponde 200 a un
+  // upgrade). Obbligare la dipendenza rende impossibile ricreare il difetto
+  // per dimenticanza, invece di affidarsi a un test che enumera gli ingressi.
+  if (typeof attachUpgrade !== 'function') {
+    throw new Error('reverse slot listeners richiede attachUpgrade');
+  }
   const listeners = new Map(); // local target port -> owned server + immutable expected tuple
   async function open({ nodeName, remotePort, generation, instanceId, secret }) {
@@ -33,6 +41,7 @@ function createReverseSlotListeners({ app, createServerImpl = http.createServer,
     }
     if (typeof secret !== 'string' || !secret) throw new Error('reverse slot listener credential mancante');
     const server = createServerImpl(app);
+    attachUpgrade(server);
     let address;
     try { address = await listen(server, { host: '127.0.0.1', port: 0, exclusive: true }); }
     catch (error) { try { server.close(); } catch (_) {} throw error; }

package/lib/nodes/reverse-slot-proof.js CHANGED Viewed

@@ -96,6 +96,16 @@ async function probeReverseSlot({ port, secret, expected, fetchImpl = fetch, tim
     const response = await fetchImpl(`http://127.0.0.1:${port}/reverse-slot-proof`, {
       method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(probe), signal: ctrl.signal,
     });
+    // Un 409 e' la RISPOSTA di un listener corretto che ha valutato la tupla e
+    // l'ha rifiutata: e' un esito, non un'assenza. Collassarlo in
+    // "non ottenuta" lo renderebbe indistinguibile da un timeout, e chi
+    // classifica gli errori tratterebbe come transitorio un mismatch reale.
+    if (response && response.status === 409) {
+      const failure = await response.json().catch(() => null);
+      const code = failure && typeof failure.code === 'string' && /^[a-z0-9-]{1,64}$/.test(failure.code)
+        ? failure.code : 'reverse-slot-proof-mismatch';
+      return { owned: false, code };
+    }
     if (!response || response.status !== 200) return { owned: false, code: 'reverse-slot-proof-unavailable' };
     const body = await response.json().catch(() => null);
     return verifySlotProof({ secret, expected, challenge: probe, response: body });

package/lib/nodes/topology-cache.js CHANGED Viewed

@@ -17,13 +17,22 @@ function defaultPath(home = os.homedir()) {
 function parseEntry(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
   const keys = Object.keys(raw).sort();
-  if (keys.some((k) => !['instanceId', 'lastSeen', 'name', 'route'].includes(k))) return null;
+  if (keys.some((k) => !['instanceId', 'lastSeen', 'name', 'route', 'label'].includes(k))) return null;
   if (!NODE_ID_RE.test(raw.instanceId) || !NODE_NAME_RE.test(raw.name)) return null;
   if (!Array.isArray(raw.route) || raw.route.length < 2 || raw.route.length > MAX_HOPS) return null;
   if (raw.route.some((x) => !NODE_NAME_RE.test(x)) || new Set(raw.route).size !== raw.route.length) return null;
   if (raw.name !== raw.route[raw.route.length - 1]) return null;
   if (!Number.isInteger(raw.lastSeen) || raw.lastSeen < 0) return null;
-  return { instanceId: raw.instanceId, name: raw.name, route: [...raw.route], lastSeen: raw.lastSeen };
+  // La label persiste solo se rispetta la stessa forma accettata altrove: un
+  // file di cache e' un ingresso come un altro e non deve poter reintrodurre
+  // testo che non produrremmo mai.
+  const label = typeof raw.label === 'string' && raw.label.trim()
+    && raw.label.trim().length <= 64 && !/[\x00-\x1f\x7f]/.test(raw.label.trim())
+    ? raw.label.trim() : null;
+  return {
+    instanceId: raw.instanceId, name: raw.name, route: [...raw.route],
+    ...(label ? { label } : {}), lastSeen: raw.lastSeen,
+  };
 }
 function parseCache(raw) {

package/lib/proxy/federation.js CHANGED Viewed

@@ -17,6 +17,48 @@ const { signHop, HOP_HEADER } = require('./hop-proof.js');
 const MAX_HOPS = 4;
 const ROUTE_DELIMITER = '_';
 const TOPOLOGY_PEER_TIMEOUT_MS = 1500;
+// Finestra di attesa del reverse channel su Share ON: limitata per non
+// diventare un retry storm, ma sufficiente al bind subito dopo un pairing.
+const SHARE_HEALTH_ATTEMPTS = 10;
+const SHARE_HEALTH_DELAY_MS = 300;
+const SHARE_NOT_READY_CODE = 'share-channel-not-ready';
+// 500/502/503/504 sono indisponibilita' che passano; 501 e 505 no.
+const TRANSIENT_HTTP_STATUS = new Set([500, 502, 503, 504]);
+// Esiti della prova di slot che significano "non ottenuta" e non "sbagliata".
+const SLOT_PROOF_UNAVAILABLE = 'reverse-slot-proof-unavailable';
+// Classificazione dell'esito di Share ON. La regola e' fail-closed sul
+// RITENTATIVO: e' ritentabile solo cio' che e' dimostrabilmente transitorio —
+// il canale non ancora salito. Tutto il resto (credenziale non valida, nodo
+// sbagliato in fondo al tunnel, prova di slot non corrispondente) e' un guasto
+// che il tempo non ripara, e ritentarlo nasconde all'operatore la vera causa.
+function classifyShareFailure(health) {
+  const detail = (health && health.detail) || 'reverse SSH non pronto';
+  if (!health) return { code: 'share-peer-unreachable', detail };
+  // Credenziale non valida: serve un re-pair, il tempo non la ripara.
+  if (health.auth === 'failed') return { code: 'share-peer-unauthorized', detail };
+  if (health.slotProof === true) {
+    // Attenzione: `probeReverseSlot` marca "non posseduta" anche quando la
+    // prova non e' stata OTTENUTA — timeout, connessione rifiutata, risposta
+    // non 200 — che e' un canale non ancora su, non una prova sbagliata.
+    // Confonderli renderebbe finale proprio il caso che vogliamo attendere.
+    return health.code === SLOT_PROOF_UNAVAILABLE
+      ? { code: SHARE_NOT_READY_CODE, detail }
+      : { code: 'share-slot-proof-failed', detail };
+  }
+  if (health.transport === 'down') return { code: SHARE_NOT_READY_CODE, detail };
+  // Il peer risponde ma con un errore server: indisponibilita' temporanea, non
+  // il nodo sbagliato in fondo al tunnel. Allowlist esplicita invece di "ogni
+  // 5xx": 501 e 505 dicono che quella richiesta non sara' MAI servita, e
+  // ritentarle sarebbe rumore.
+  if (TRANSIENT_HTTP_STATUS.has(health.httpStatus)) {
+    return { code: SHARE_NOT_READY_CODE, detail };
+  }
+  // Qui il peer ha risposto 200 ma non e' quello atteso (instanceId o payload):
+  // ritentare non lo trasforma nel nodo giusto.
+  if (health.reachability === 'failed') return { code: 'share-peer-mismatch', detail };
+  return { code: 'share-peer-unreachable', detail };
+}
 function peerFromToken(nodesPath, token) {
   const st = store.loadStore(nodesPath);
@@ -381,7 +423,18 @@ async function notifyHubShare({ node, shared, fetchImpl = fetch, timeoutMs = 500
       }, budget);
     });
     const response = await Promise.race([request, timeout]);
-    if (!response || !response.ok) throw new Error(`hub Share HTTP ${response && response.status || 'unknown'}`);
+    if (!response || !response.ok) {
+      const failure = new Error(`hub Share HTTP ${response && response.status || 'unknown'}`);
+      failure.status = response && response.status;
+      // Si estrae SOLO il codice tipizzato: il corpo remoto non entra mai nel
+      // messaggio d'errore ne' nei log. Un corpo non-JSON lascia il codice
+      // assente e l'errore resta definitivo, che e' il default sicuro.
+      try {
+        const body = typeof response.json === 'function' ? await response.json() : null;
+        if (body && typeof body.code === 'string' && body.code.length <= 64) failure.code = body.code;
+      } catch (_) { /* corpo assente o non-JSON: nessun codice */ }
+      throw failure;
+    }
     return { shared };
   } finally { clearTimeout(timer); }
 }
@@ -593,7 +646,14 @@ async function collectTopologyDetailed({
     if (!n.nodeId || seen.has(n.nodeId)
       || (!ingress && n.direction === 'inbound' && n.shared !== true)
       || (ingress && !canTransit(ingress, n))) continue;
-    out.push({ instanceId: n.nodeId, name: n.name, route: [n.name], direct: true });
+    // `name` e' lo slug locale con cui si indirizza; `label` e' il nome
+    // leggibile. Senza quest'ultimo un nodo raggiunto in transito arriva agli
+    // altri come uno slug scelto da qualcun altro, e cinque installazioni
+    // diverse si presentano con lo stesso nome.
+    out.push({
+      instanceId: n.nodeId, name: n.name, route: [n.name], direct: true,
+      label: store.validLabel(n.label) ? n.label.trim() : '',
+    });
     if (ttl <= 1 || !n.token) continue;
     probes.push({ n, pending: fetchPeerTopology({ node: n, ttl, seen, fetchImpl, timeoutMs }) });
   }
@@ -611,7 +671,15 @@ async function collectTopologyDetailed({
           || new Set(child.route).size !== child.route.length
           || child.name !== child.route[child.route.length - 1]
           || child.route.includes(n.name)) continue;
-        out.push({ instanceId: child.instanceId, name: child.name, route: [n.name, ...child.route], direct: false });
+        // La label di un nodo in transito e' testo AUTO-DICHIARATO da un altro
+        // nodo: si accetta solo se rispetta la stessa forma di una label locale,
+        // altrimenti si resta senza nome invece di propagare qualcosa di
+        // arbitrario. Non e' mai una prova di identita': quella e' l'instanceId.
+        out.push({
+          instanceId: child.instanceId, name: child.name,
+          route: [n.name, ...child.route], direct: false,
+          label: store.validLabel(child.label) ? child.label.trim() : '',
+        });
     }
   }
   const ids = new Set(); const routes = new Set(); const unique = [];
@@ -653,7 +721,15 @@ async function collectLocalTopology({
     next.set(entry.instanceId, entry);
   }
   for (const n of live.nodes) {
-    if (n.route.length > 1) next.set(n.instanceId, { instanceId: n.instanceId, name: n.name, route: [...n.route], lastSeen: now });
+    // La cache conserva anche la label: senza, un nodo che torna stale perde il
+    // nome e ricompare come slug, cioe' esattamente il difetto che si voleva
+    // togliere. Resta un dato riferito, non una prova.
+    if (n.route.length > 1) {
+      next.set(n.instanceId, {
+        instanceId: n.instanceId, name: n.name, route: [...n.route],
+        ...(n.label ? { label: n.label } : {}), lastSeen: now,
+      });
+    }
   }
   const cached = [...next.values()].sort((a, b) => a.route.join('/').localeCompare(b.route.join('/'))).slice(0, topologyCache.MAX_ENTRIES);
   const serialized = { schemaVersion: topologyCache.SCHEMA_VERSION, nodes: cached };
@@ -895,12 +971,19 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
     }
     try {
       if (body.shared) {
+        // Il reverse channel viene stabilito dal peer subito prima di questa
+        // chiamata: appena dopo un pairing il bind non e' ancora pronto e la
+        // finestra breve trasformava un'attesa in un fallimento definitivo,
+        // con rollback dell'intera transazione lato peer. La finestra resta
+        // limitata (nessun retry storm) ma copre il caso reale.
         let health;
         if (req.peer.reversePool) {
-          for (let attempt = 0; attempt < 6; attempt += 1) {
+          for (let attempt = 0; attempt < SHARE_HEALTH_ATTEMPTS; attempt += 1) {
             health = await probeReverseOwner(req.peer, fetchImpl || fetch);
             if (health.status === 'healthy') break;
-            if (attempt < 5) await new Promise((resolve) => setTimeout(resolve, 200));
+            if (attempt < SHARE_HEALTH_ATTEMPTS - 1) {
+              await new Promise((resolve) => setTimeout(resolve, SHARE_HEALTH_DELAY_MS));
+            }
           }
         } else {
           health = await waitForHealthyPeer({
@@ -908,14 +991,19 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
             token: req.peer.token,
             expectedInstanceId: req.peer.nodeId || null,
             fetchImpl: fetchImpl || fetch,
-            attempts: 6,
-            delayMs: 200,
+            attempts: SHARE_HEALTH_ATTEMPTS,
+            delayMs: SHARE_HEALTH_DELAY_MS,
           });
         }
         if (health.status !== 'healthy') {
+          // Codice tipizzato: chi chiama deve poter distinguere un'attesa da un
+          // guasto definitivo senza interpretare una stringa. Solo il canale
+          // non ancora salito e' ritentabile.
+          const failure = classifyShareFailure(health);
           return res.status(409).json({
             error: 'canale share non raggiungibile',
-            detail: health.detail || 'reverse SSH non pronto',
+            code: failure.code,
+            detail: failure.detail,
           });
         }
       }
@@ -980,7 +1068,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,
+  MAX_HOPS, ROUTE_DELIMITER, TOPOLOGY_PEER_TIMEOUT_MS, SHARE_NOT_READY_CODE, classifyShareFailure,
   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 CHANGED Viewed

@@ -187,9 +187,20 @@ function createServer(opts = {}) {
     const key = reverseKey(active.port, expectedGeneration);
     const existing = entries.get(key);
     if (existing) return existing;
+    // Il listener prova la PROPRIA identita' a chi compone la sfida, e l'altro
+    // capo la costruisce con l'id di QUESTA installazione (probeReverseOwner usa
+    // `peer.nodeId`, cioe' noi visti da lui). `node.nodeId` e' invece l'id del
+    // nodo REMOTO — lo store lo impone, rifiutando come self-reference una voce
+    // il cui nodeId eguagli il proprio. Registrarlo faceva firmare due tuple
+    // diverse ai due capi: la prova non tornava mai e Share si spegneva con un
+    // errore definitivo, non ritentabile.
+    const localInstanceId = (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
+    // Fail-closed: senza identita' locale il listener nascerebbe con una prova
+    // che nessuno puo' validare. Meglio non aprirlo che aprirlo indimostrabile.
+    if (!localInstanceId) return null;
     const listener = await reverseSlotListeners.open({
       nodeName: node.name, remotePort: active.port, generation: expectedGeneration,
-      instanceId: node.nodeId, secret: node.acceptToken,
+      instanceId: localInstanceId, secret: node.acceptToken,
     });
     let launched = nodesTunnel.startReverseForward({
       home: cfg.home || os.homedir(), node, remotePort: active.port, generation: expectedGeneration,
@@ -227,15 +238,19 @@ function createServer(opts = {}) {
     }
     const selected = [...entries.values()].filter((entry) => (remotePort === null || entry.remotePort === remotePort)
       && (generation === null || entry.generation === generation));
-    let stopped = false;
+    // Il valore di ritorno significa "TUTTE le entry selezionate sono spente in
+    // modo dimostrabile". Durante la grace di una rotazione ne coesistono due:
+    // dichiarare successo perche' UNA e' stata chiusa lascerebbe l'altra viva
+    // mentre chi chiama registra il canale come privato.
+    const outcomes = [];
     for (const existing of selected) {
       const result = nodesTunnel.stopTunnel({ home: cfg.home || os.homedir(), name: nodesTunnel.reverseTunnelName(name, existing.remotePort, existing.generation) });
+      outcomes.push(result);
       // If we cannot prove ownership we neither signal nor close the listener:
       // the channel is quarantined for diagnostics rather than broken by us.
-      if (!result.stopped && !['no pidfile', 'stale (pid dead)'].includes(result.reason)) continue;
+      if (!reverseRotation.stopWasDemonstrated(result)) continue;
       entries.delete(reverseKey(existing.remotePort, existing.generation));
       await reverseSlotListeners?.closePort(existing.localPort);
-      stopped = true;
     }
     if (!entries.size) rotatableReverse.delete(name);
     if (remotePort === null && generation === null) {
@@ -243,7 +258,11 @@ function createServer(opts = {}) {
       if (watcher) clearInterval(watcher);
       reverseWatchers.delete(name);
     }
-    return stopped;
+    // La decisione vive in `summarizeStops` (funzione pura, testabile senza
+    // processi): successo solo se qualcosa e' stato spento E niente e' rimasto
+    // in quarantena. Il caso "nessuna entry" resta false come prima: non si
+    // puo' dimostrare nulla.
+    return reverseRotation.summarizeStops(outcomes).allClosed;
   }
   async function verifyRotatablePool(node) {
     const pool = node?.reversePool;
@@ -473,7 +492,12 @@ function createServer(opts = {}) {
   }
   const app = express();
-  reverseSlotListeners = createReverseSlotListeners({ app, diagnostics, createServerImpl: cfg.reverseSlotCreateServerImpl });
+  reverseSlotListeners = createReverseSlotListeners({
+    app, diagnostics, createServerImpl: cfg.reverseSlotCreateServerImpl,
+    // `routeUpgrade` e' hoisted: qui si cattura solo il riferimento, la
+    // chiamata avviene quando arriva un upgrade, a server avviato.
+    attachUpgrade: (slotServer) => slotServer.on('upgrade', routeUpgrade),
+  });
   const distDir = path.join(__dirname, '..', 'frontend', 'dist');
   // no-store on everything (HTML+assets+API): this is a local, token-adjacent tool.
   app.use((_req, res, next) => { res.set('Cache-Control', 'no-store'); next(); });
@@ -795,7 +819,13 @@ function createServer(opts = {}) {
   }, opts.wsHeartbeatMs || 30000);
   if (typeof heartbeat.unref === 'function') heartbeat.unref();
   server.on('close', () => clearInterval(heartbeat));
-  server.on('upgrade', (req, socket, head) => {
+  // Routing dell'upgrade WS. Dichiarata come funzione (hoisted nello scope di
+  // createServer) perche' i listener per-slot nascono PRIMA di questo punto e
+  // devono ricevere lo STESSO routing: un listener che serve `app` senza
+  // handler di upgrade fa cadere l'upgrade su Express, che non ha una rotta
+  // HTTP `/ws` e risponde con la SPA (200) invece di 101 -> terminale nero su
+  // ogni peer raggiunto via reverse pool.
+  function routeUpgrade(req, socket, head) {
     let pathname;
     try { pathname = new URL(req.url, 'http://127.0.0.1').pathname; }
     catch (_) { try { socket.destroy(); } catch (_e) {} return; }
@@ -826,7 +856,8 @@ function createServer(opts = {}) {
       return;
     }
     try { socket.destroy(); } catch (_) {}
-  });
+  }
+  server.on('upgrade', routeUpgrade);
   wss.on('connection', (ws, req) => {
     ws.isAlive = true;
     ws.on('pong', () => { ws.isAlive = true; });