@mmmbuto/nexuscrew 0.9.4 → 0.9.6

package/lib/nodes/commands.js

@@ -204,8 +204,14 @@ function nodesAdd(opts) {
 
   log(`nodes add: nodo "${name}" aggiunto (ssh ${ssh}${sshPort ? `:${sshPort}` : ''}, nexus remoto ${remotePort} -> locale ${localPort})`);
   log('Incolla nel ~/.ssh/authorized_keys del NODO (lato forward, chiave dedicata):');
-  // permitopen vincola i -L alla SOLA porta nexus remota; command=/bin/false + restrict.
-  if (pub) log(`restrict,port-forwarding,permitopen="127.0.0.1:${remotePort}",command="/bin/false" ${pub}`);
+  // R19: permitopen con le destinazioni EXPLICITE dei -L. Qui si conosce solo
+  // la porta nexus: la porta pannello del peer la annuncia il JOIN, non
+  // esiste ancora — quando apparirà, la riga completa (due destinazioni) la
+  // emette il pairing. Mai un permesso generico: è ciò che impedisce a questa
+  // chiave di aprire canali arbitrari. command=/bin/false + restrict.
+  const panelRemotePort = opts.panelRemotePort !== undefined ? Number(opts.panelRemotePort) : undefined;
+  const riga = tunnel.authorizedKeysLine({ remotePort, panelRemotePort, pub });
+  if (riga) log(riga);
   return { code: 0, name, sshPort, localPort, remotePort, transport: entry.transport };
 }
 

package/lib/nodes/health.js

@@ -102,6 +102,7 @@ async function nodeHealth({ node, home, fetchImpl, now = Date.now(), force = fal
         transport: 'down', auth: 'unknown', reachability: 'unknown', status: 'down',
         detail: diagnostic.detail, code: diagnostic.code, stage: diagnostic.stage,
         ...(diagnostic.hint ? { hint: diagnostic.hint } : {}),
+        ...(diagnostic.authorizedKeys ? { authorizedKeys: diagnostic.authorizedKeys } : {}),
         transportEngine: ts.transport || 'ssh', managed: ts.managed !== false, at: now,
       };
     } else if (!node.token) {

package/lib/nodes/peer-transitions.js

@@ -65,10 +65,16 @@ function recordPeerTransition(nodeName, health, diagnostics) {
       `${nodeName}: tunnel ${previous.tunnel} -> ${tunnel}`,
       { node: nodeName, state: tunnel });
   }
-  // Testabile solo quando il tunnel e' su ORA: se e' appena caduto, il
-  // servizio e' passato a 'unknown' come artefatto del tunnel (gia' segnalato
-  // sopra), non come un fatto nuovo — quindi qui non si scrive nulla.
-  if (tunnel === 'up' && previous.service !== service) {
+  // Testabile solo quando il tunnel era SU e resta SU: solo allora entrambi
+  // gli estremi del confronto sono misure vere. Se e' appena caduto, il
+  // servizio passa a 'unknown' come artefatto del tunnel (gia' segnalato
+  // sopra), non come un fatto nuovo. Per SIMMETRIA vale anche al contrario:
+  // se e' appena tornato, il servizio non e' "tornato" — e' semplicemente di
+  // nuovo osservabile, e 'unknown' non era una misura precedente da cui
+  // partire. Scrivere "unknown -> ok" alla ripresa sarebbe un fatto inventato
+  // tanto quanto lo sarebbe "ok -> unknown" alla caduta: un record diagnostico
+  // che dichiara misurato cio' che non lo e' stato e' peggio del silenzio.
+  if (previous.tunnel === 'up' && tunnel === 'up' && previous.service !== service) {
     diagnostics.record('warn', 'peer-health', 'SERVICE_TRANSITION',
       `${nodeName}: service ${previous.service} -> ${service}`,
       { node: nodeName, state: service });

package/lib/nodes/pubkey-format.js

@@ -0,0 +1,69 @@
+'use strict';
+// Un SOLO formatter al confine UI/log per gli esiti del resolver della
+// pubblica (job 5, strutturale). Prima le frasi si componevano in basso —
+// nel supervisor e nella route — dove non si sa abbastanza per scriverle:
+// meta' della 0.9.5 e' nata cosi' (promesse false, cause enumerate «a caso»,
+// silenzi). Ora il resolver produce DATI enumerati (resolvePublicKey in
+// tunnel.js) e QUESTO punto unico li trasforma in frasi. Un test per ogni
+// causa.
+
+const path = require('node:path');
+const {
+  PUBKEY_DERIVED, PUBKEY_NO_IDENTITY, PUBKEY_ACTUAL_KEY_UNKNOWN,
+  PUBKEY_TOOL_UNAVAILABLE, PUBKEY_ENCRYPTED_OR_UNREADABLE,
+} = require('./tunnel.js');
+
+// La frase della CAUSA per ogni esito — il «perche'» che chi guarda deve
+// leggere. `resolution` e' il dato del risolutore; `identityFile` il path
+// dichiarato, per nominare l'oggetto giusto. Non inventare mai una causa che
+// il dato non porta: l'ignosciuto si dice sconosciuto, non si indovina.
+function pubkeyCauseText(resolution, { identityFile } = {}) {
+  const nome = identityFile ? path.basename(identityFile) : null;
+  switch (resolution && resolution.outcome) {
+    case PUBKEY_DERIVED:
+      // Nessuna causa da dichiarare: la riga c'e'.
+      return null;
+    case PUBKEY_NO_IDENTITY:
+      return `la chiave dichiarata${nome ? ` (${nome})` : ''} non esiste dove dovrebbe`;
+    case PUBKEY_ACTUAL_KEY_UNKNOWN:
+      return 'nessun -i: ssh usa le chiavi di default, un agent o la config, e da qui non si sa quale';
+    case PUBKEY_TOOL_UNAVAILABLE:
+      return 'ssh-keygen non e\' disponibile su questa macchina: la pubblica non si puo\' derivare';
+    case PUBKEY_ENCRYPTED_OR_UNREADABLE:
+      return `non riesco a derivare la pubblica da ${nome || 'quella chiave'}: e' cifrata o illeggibile`;
+    default:
+      // Al confine, l'ignosciuto si NOMINA: un silenzio qui sarebbe lo stesso
+      // difetto che questo modulo chiude.
+      return `esito non riconosciuto: ${resolution && resolution.outcome}`;
+  }
+}
+
+// L'AZIONE suggerita per ogni esito — il «cosa fare» accanto al perche'.
+// Aspettare non serve dove bisogna concedere; riprovare non serve dove la
+// condizione dipende da una decisione altrove.
+function pubkeyActionText(resolution) {
+  switch (resolution && resolution.outcome) {
+    case PUBKEY_DERIVED:
+      return 'sostituisci la riga in ~/.ssh/authorized_keys del nodo con questa';
+    case PUBKEY_NO_IDENTITY:
+      return 'verifica il path della chiave dichiarata per questo nodo';
+    case PUBKEY_ACTUAL_KEY_UNKNOWN:
+      return 'individua la chiave che ssh usa davvero e modifica A MANO la sua riga';
+    case PUBKEY_TOOL_UNAVAILABLE:
+      return 'installa ssh-keygen (openssh-client), poi riprova';
+    case PUBKEY_ENCRYPTED_OR_UNREADABLE:
+      return 'usa una chiave dedicata non cifrata per questo nodo, o modifica A MANO la riga';
+    default:
+      return 'verifica la configurazione del nodo';
+  }
+}
+
+// La nota del pairing quando la riga c'e': il testo che accompagnava la
+// risposta, ora composto qui (l'unico punto) e non nella route.
+function pubkeyPairingNote(resolution, { panelPort } = {}) {
+  if (!resolution || resolution.outcome !== PUBKEY_DERIVED) return null;
+  return 'il peer ha un pannello sulla propria porta ' + panelPort
+    + ': SOSTITUISCI la riga già installata in ~/.ssh/authorized_keys del NODO con questa (due destinazioni), altrimenti il canale del pannello sarà rifiutato. È la riga della chiave DICHIARATA per questo nodo (-i), non un\'eventuale chiave "jump" dello stesso nodo. Se ssh sceglie un\'altra identità (agent o config), la riga giusta è quella della chiave che usa davvero.';
+}
+
+module.exports = { pubkeyCauseText, pubkeyActionText, pubkeyPairingNote };

package/lib/nodes/tunnel-supervisor.js

@@ -21,6 +21,24 @@ const ownershipGraceMs = Number.isFinite(ownershipGraceRaw) && ownershipGraceRaw
 const reverseFailureMaxRaw = Number(process.env.NEXUSCREW_TUNNEL_REVERSE_FAILURE_MAX || 8);
 const reverseFailureMax = Number.isInteger(reverseFailureMaxRaw) && reverseFailureMaxRaw >= 1
   ? Math.min(reverseFailureMaxRaw, 32) : 8;
+// R19 seguito — contratto per la sonda del canale -L quando non conclude MAI:
+// continuare a sondare ogni 250ms e' giusto per la finestra transitoria (il
+// servizio remoto non e' ancora su dopo un restart/aggiornamento: la prossima
+// sonda e' una connessione FRESCA, si qualifica da sola appena il servizio
+// risponde) ma sbagliato oltre — un vero permitopen mancante o un servizio
+// remoto permanentemente giu' non si risolvono mai da soli, e la sonda gira
+// per sempre senza mai diventare osservabile ne' degradare, la stessa cosa
+// che l'assenza di storia delle transizioni peer faceva prima di questo
+// registro. 60 tentativi * 250ms = 15s, lo stesso budget di attesa gia' in
+// uso altrove in questo prodotto per "il runtime e' tornato sano dopo un
+// riavvio" (vedi healthAttempts/healthDelayMs in lib/update/runner.js): oltre
+// quella soglia il canale entra in degraded, ESATTAMENTE come il fallimento
+// del forward inverso — stesso stato, stessa auto-guarigione a cadenza fissa,
+// mai un "pronto" dichiarato senza averlo verificato (sarebbe la stessa bugia
+// che R19 ha tolto, solo con una bandiera "non verificato" appesa sopra).
+const channelProbeMaxRaw = Number(process.env.NEXUSCREW_TUNNEL_CHANNEL_PROBE_MAX || 60);
+const channelProbeMax = Number.isInteger(channelProbeMaxRaw) && channelProbeMaxRaw >= 1
+  ? Math.min(channelProbeMaxRaw, 240) : 60;
 // Once the initial reverse-forward budget is exhausted the supervisor does NOT
 // die: it stays "degraded" and retries at the fixed production cadence of 60s,
 // so a transient reverse listener on the hub (e.g. a mobile reconnect) heals on
@@ -32,7 +50,7 @@ const steadyRetryMsRaw = Number(steadyRetryTestMode ? (process.env.NEXUSCREW_TUN
 const steadyRetryMinMs = steadyRetryTestMode ? 1 : 60000;
 const steadyRetryMs = Number.isFinite(steadyRetryMsRaw) && steadyRetryMsRaw >= steadyRetryMinMs
   ? Math.min(steadyRetryMsRaw, 120000) : 60000;
-if (!sshBin || !statePath || !pidPath || !runId) process.exit(2);
+if (require.main === module && (!sshBin || !statePath || !pidPath || !runId)) process.exit(2);
 
 let child = null;
 let stopping = false;
@@ -44,18 +62,25 @@ let forwardSocket = null;
 let ownershipWaitTimer = null;
 let ownershipTimer = null;
 let reverseFailures = 0;
+let channelRefusedLogged = false;
+let channelProbeFailures = 0;
 
 function localForwardPort(args) {
+  return localForwardPorts(args)[0] || null;
+}
+function localForwardPorts(args) {
+  const ports = [];
   for (let i = 0; i < args.length - 1; i += 1) {
     if (args[i] !== '-L') continue;
-    const match = String(args[i + 1] || '').match(/^127\.0\.0\.1:(\d+):127\.0\.0\.1:\d+$/);
+    const match = String(args[i + 1] || '').match(/^127\.0\.0\.1:(\d+):127\.0\.0\.1:(\d+)$/);
     const port = match ? Number(match[1]) : 0;
-    if (Number.isInteger(port) && port >= 1 && port <= 65535) return port;
+    if (Number.isInteger(port) && port >= 1 && port <= 65535 && !ports.includes(port)) ports.push(port);
   }
-  return null;
+  return ports;
 }
 
 const forwardPort = localForwardPort(sshArgs);
+const forwardPorts = localForwardPorts(sshArgs);
 
 function reverseForwardPort(args) {
   for (let i = 0; i < args.length - 1; i += 1) {
@@ -86,6 +111,106 @@ function clearForwardProbe() {
 // blocked connecting to an unreachable endpoint. Opening the local -L socket
 // forces OpenSSH to establish the real forward channel. Only that event may
 // advertise transport-ready or reset retry backoff.
+//
+// R19: connect NON è prova di canale. OpenSSH accetta la TCP sul listener
+// locale SUBITO e chiede il canale al server DOPO: se il server lo nega
+// (permitopen senza quella destinazione) il socket viene CHIUSO nel giro di
+// millisecondi — bind locale riuscito, canale morto. Una finestra di grazia
+// dopo connect distingue le due metà: «il canale è aperto» da «il server ha
+// rifiutato». Ready senza questa prova misura la metà comoda.
+const CHANNEL_GRACE_MS = 350;
+
+// Pura (con net iniettabile): per ogni porta locale -L riporta
+// 'channel-ok' | 'channel-refused' | 'bind-failed'.
+function probeForwardChannels({ ports, graceMs = CHANNEL_GRACE_MS, connect = net.connect } = {}) {
+  return new Promise((resolveOuter) => {
+    const esiti = new Map();
+    const sockets = [];
+    let pending = ports.length;
+    if (!pending) return resolveOuter(esiti);
+    const settle = (port, esito, sock) => {
+      if (!esiti.has(port)) {
+        esiti.set(port, esito);
+        if (sock) { try { sock.destroy(); } catch (_) {} }
+        pending -= 1;
+        if (pending <= 0) resolveOuter(esiti);
+      }
+    };
+    for (const port of ports) {
+      const sock = connect({ host: '127.0.0.1', port });
+      sockets.push(sock);
+      let connected = false;
+      let graceTimer = null;
+      sock.setTimeout(1000);
+      sock.once('connect', () => {
+        connected = true;
+        // La finestra che decide: se entro graceMs il socket muore, il canale
+        // è stato negato dall'altro capo (o chiuso da lui): non è nostro.
+        graceTimer = setTimeout(() => settle(port, 'channel-ok', sock), graceMs);
+      });
+      const morte = () => {
+        if (graceTimer) clearTimeout(graceTimer);
+        settle(port, connected ? 'channel-refused' : 'bind-failed', sock);
+      };
+      sock.once('close', morte);
+      sock.once('error', morte);
+      sock.once('timeout', morte);
+    }
+  });
+}
+
+// R19 punto 3: chi ha installato la chiave quando il pannello non esisteva è
+// rotto e NON lo sapeva. Il prodotto lo DICE, con la riga da sostituire: le
+// destinazioni arrivano dagli `-L`, la pubblica si DERIVA dalla privata
+// indicata da `-i`. Quando non si riesce a derivarla, dice comunque COSA
+// aggiungere — mai una riga a metà.
+// La riga e' un DATO, non una frase: chi la deve mostrare non deve ritagliarla
+// da un testo costruito qui. `hint` resta per chi legge un log;
+// `authorizedKeys` e' il campo che la UI consuma, e resta vuoto quando la riga
+// completa non si puo' comporre.
+// I DUE RAMI NON DICONO LA STESSA COSA, e prima la dicevano: senza la chiave
+// pubblica si costruiva un FRAMMENTO ("aggiungi a permitopen: ...") e lo si
+// infilava nella frase "Riga da usare (SOSTITUISCI quella esistente)". Chi
+// avesse obbedito avrebbe sostituito una riga valida con mezza riga, rompendo
+// l'accesso invece di ripararlo: una promessa falsa che peggiora il guasto.
+// Con la chiave: riga completa, sostituzione, ed e' anche il campo copiabile.
+// Senza: si dice che la chiave non e' identificabile e si chiede una modifica
+// A MANO della riga esistente, mostrando solo le destinazioni da aggiungere.
+function refusalDetails({ remoteDestinations, identityFile } = {}) {
+  const dests = (remoteDestinations || []).join('",permitopen="');
+  // Esito enumerato (resolver) + frase composta al confine UI/log — il punto
+  // unico pubkey-format. Prima qui si sceglieva fra cause che non si potevano
+  // distinguere e le si enumerava «a caso»; ora il dato distingue, e il
+  // testo dice la causa ESATTA: mai inventarne una che il dato non porta.
+  const resolution = require('./tunnel.js').resolvePublicKey(identityFile);
+  const { pubkeyCauseText, pubkeyActionText } = require('./pubkey-format.js');
+  const premessa = 'canale rifiutato dal NODO remoto: la chiave in ~/.ssh/authorized_keys non autorizza queste destinazioni.';
+  if (resolution.outcome !== require('./tunnel.js').PUBKEY_DERIVED) {
+    const causa = pubkeyCauseText(resolution, { identityFile });
+    const azione = pubkeyActionText(resolution);
+    return {
+      hint: `${premessa} NON posso identificare la chiave da correggere — ${causa}. ${azione}`
+        + `: aggiungi queste destinazioni: permitopen="${dests}"`,
+      authorizedKeys: '',
+      outcome: resolution.outcome,
+    };
+  }
+  const riga = `restrict,port-forwarding,permitopen="${dests}",command="/bin/false" ${resolution.line}`;
+  // NON diciamo «quella con cui il supervisor si autentica»: `-i` DICHIARA
+  // un'identita', non la impone — senza `IdentitiesOnly=yes` OpenSSH puo'
+  // comunque usare l'agent o la config, e il canale essere autenticato da
+  // un'altra chiave. Affermarlo sarebbe una promessa che il comando non
+  // mantiene, e manderebbe a sostituire la riga sbagliata.
+  const quale = identityFile ? ` (chiave DICHIARATA per questo nodo: ${path.basename(identityFile)}, non un'eventuale chiave "jump" dello stesso nodo; se ssh ne sceglie un'altra via agent o config, la riga da correggere e' quella)` : '';
+  return {
+    hint: `${premessa} Riga da usare (SOSTITUISCI quella esistente, non aggiungerne una seconda)${quale}: ${riga}`,
+    authorizedKeys: riga,
+    outcome: resolution.outcome,
+  };
+}
+
+function refusalHint(opts) { return refusalDetails(opts).hint; }
+
 function probeForward(expectedChild) {
   if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
   if (!forwardPort) {
@@ -99,29 +224,72 @@ function probeForward(expectedChild) {
     if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'reverse-forward' })) stop();
     return;
   }
-  let settled = false;
-  const socket = net.connect({ host: '127.0.0.1', port: forwardPort });
-  forwardSocket = socket;
-  const done = (ready) => {
-    if (settled) return;
-    settled = true;
-    try { socket.destroy(); } catch (_) {}
-    if (forwardSocket === socket) forwardSocket = null;
+  const ports = forwardPorts.length ? forwardPorts : [forwardPort];
+  probeForwardChannels({ ports, graceMs: CHANNEL_GRACE_MS }).then((esiti) => {
     if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
-    if (ready) {
+    const rifiutate = ports.filter((p) => esiti.get(p) === 'channel-refused');
+    const mancanti = ports.filter((p) => esiti.get(p) === 'bind-failed');
+    if (!rifiutate.length && !mancanti.length) {
       attempt = 0;
       reverseFailures = 0;
-      logEvent(`forward ready stableMs=${stableMs}`);
-      if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'tcp-forward' })) stop();
+      channelProbeFailures = 0;
+      logEvent(`forward ready stableMs=${stableMs} channel=verified`);
+      if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'tcp-forward-verified' })) stop();
       return;
     }
-    if (!writeState('transport-probing', { sshPid: child.pid, stableMs })) return stop();
+    if (rifiutate.length && !channelRefusedLogged) {
+      // Una volta per generazione: il ciclo di probing continua (la
+      // concessione può essere aggiornata), ma chi guarda SA qual è la metà
+      // malata e COSA sostituire.
+      channelRefusedLogged = true;
+      logEvent(refusalHint({ remoteDestinations: remoteDestinationsOf(sshArgs), identityFile: identityFileOf(sshArgs) }));
+    }
+    channelProbeFailures += 1;
+    if (channelProbeFailures > channelProbeMax) {
+      // Budget esaurito: la finestra transitoria (servizio remoto non ancora
+      // su) aveva 15s per qualificarsi da sola con una sonda fresca ogni
+      // volta — non l'ha fatto. Da qui in poi non e' piu' "sta per succedere",
+      // e continuare a sondare ogni 250ms sarebbe la stessa sonda che gira
+      // per sempre senza mai diventare osservabile. Stesso stato del forward
+      // inverso: degraded, vivo, si riprova a cadenza fissa — mai "pronto"
+      // dichiarato senza averlo verificato.
+      return enterDegraded({
+        code: 'forward-channel-blocked',
+        detail: rifiutate.length
+          ? `canale rifiutato dal nodo remoto dopo ${channelProbeFailures} sonde`
+          : `nessun canale locale disponibile dopo ${channelProbeFailures} sonde`,
+        ...(rifiutate.length
+          ? (() => {
+            const d = refusalDetails({ remoteDestinations: remoteDestinationsOf(sshArgs), identityFile: identityFileOf(sshArgs) });
+            return { hint: d.hint, ...(d.authorizedKeys ? { authorizedKeys: d.authorizedKeys } : {}) };
+          })()
+          : {}),
+      });
+    }
+    if (!writeState('transport-probing', {
+      sshPid: child.pid, stableMs,
+      ...(rifiutate.length ? { probeDetail: 'channel-refused', refusedLocalPorts: rifiutate } : {}),
+      ...(mancanti.length ? { probeDetail: 'bind-failed', missingLocalPorts: mancanti } : {}),
+    })) return stop();
     forwardProbeTimer = setTimeout(() => probeForward(expectedChild), 250);
-  };
-  socket.setTimeout(1000);
-  socket.once('connect', () => done(true));
-  socket.once('error', () => done(false));
-  socket.once('timeout', () => done(false));
+  });
+}
+
+// Le destinazioni REMOTE degli -L, nella forma che vive in permitopen.
+function remoteDestinationsOf(args) {
+  const out = [];
+  for (let i = 0; i < args.length - 1; i += 1) {
+    if (args[i] !== '-L') continue;
+    const m = String(args[i + 1] || '').match(/^127\.0\.0\.1:\d+:(127\.0\.0\.1:\d+)$/);
+    if (m && !out.includes(m[1])) out.push(m[1]);
+  }
+  return out;
+}
+function identityFileOf(args) {
+  for (let i = 0; i < args.length - 1; i += 1) {
+    if (args[i] === '-i') return args[i + 1];
+  }
+  return null;
 }
 
 function ownsGeneration() {
@@ -169,10 +337,21 @@ function enterDegraded(diagnosis) {
   // it cannot identify the process holding a listener on the hub.  Never turn
   // local pidfile ownership into a false remote-listener attribution.
   const ownership = 'unknown';
-  logEvent(`ssh degraded code=${safe.code} reversePort=${reversePort || 'none'} ownership=${ownership} failures=${reverseFailures} steadyRetryMs=${steadyRetryMs}`);
+  // Il contatore che si logga dipende da QUALE budget si e' esaurito: il
+  // canale -L (channelProbeFailures) e il forward inverso (reverseFailures)
+  // sono guasti indipendenti sullo stesso processo (vedi CHANNEL_GRACE_MS
+  // sopra) — loggare sempre reverseFailures direbbe "0" su un degraded di
+  // canale, come se non fosse mai stato provato.
+  const failures = safe.code === 'forward-channel-blocked' ? channelProbeFailures : reverseFailures;
+  logEvent(`ssh degraded code=${safe.code} reversePort=${reversePort || 'none'} ownership=${ownership} failures=${failures} steadyRetryMs=${steadyRetryMs}`);
   if (!writeState('degraded', {
     code: safe.code, detail: safe.detail,
     ...(safe.hint ? { hint: safe.hint } : {}),
+    // Il campo viaggia insieme alla frase, non al posto suo: chi legge un log
+    // vuole l'hint, la UI vuole la riga intera. Scriverne solo uno qui e' il
+    // modo in cui il campo si perde a meta' strada e tutto il resto della
+    // catena, gia' cablato, riceve per sempre il fallback testuale.
+    ...(safe.authorizedKeys ? { authorizedKeys: safe.authorizedKeys } : {}),
     reversePort, ownership, steadyRetryMs, terminal: false,
   })) return stop();
   // Keep the backoff counter honest for observers; the degraded retry is fixed.
@@ -180,19 +359,70 @@ function enterDegraded(diagnosis) {
   retryTimer = setTimeout(run, steadyRetryMs);
 }
 
+// R19 seguito, secondo difetto (2026-08-17, audit su develop@437d29f):
+// enterDegraded per il canale -L riusava la macchina del forward inverso
+// senza la sua precondizione implicita. Nel reverse failure `child` e' GIA'
+// null quando enterDegraded gira (handleFailure lo azzera PRIMA, perche' e'
+// il crash del processo l'evento che ci porta li'). Nel canale -L rifiutato
+// il processo NON e' morto — e' il canale a essere negato — quindi `child`
+// e' ancora vivo quando enterDegraded schedula run() per la prossima
+// generazione. run() faceva `child = spawn(...)` incondizionatamente: la
+// vecchia generazione, ancora viva, restava senza piu' nessuna variabile che
+// la referenzi — irraggiungibile da stop(), orfana, titolare dei suoi bind
+// per sempre. Misurato dall'auditor: due fake-ssh vivi dopo un degraded,
+// SIGTERM al supervisor ne ferma solo l'ultimo.
+//
+// La correzione non e' locale (un kill dentro enterDegraded): e' che
+// run() — l'UNICO punto che assegna `child` a un nuovo spawn — non
+// garantiva la precondizione da solo. replaceChild() e' ora quel punto
+// unico: ferma SEMPRE il child uscente (se vivo) e ne attende l'uscita
+// prima di procedere. Se non c'e' nulla da fermare (gia' null, o gia'
+// uscito — il caso reverse, verificato invariato) procede subito: la stessa
+// funzione copre correttamente entrambi i versi, nessun percorso bypassa la
+// garanzia senza dichiararlo qui.
+function replaceChild(spawnNext) {
+  const outgoing = child;
+  const proceed = () => {
+    clearTimeout(upTimer);
+    clearForwardProbe();
+    spawnNext();
+  };
+  if (!outgoing || outgoing.exitCode != null) return proceed();
+  // La generazione uscente muore per NOSTRA mano qui, non per un crash che
+  // handleFailure deve classificare: distacchiamo i suoi listener prima di
+  // ucciderla, altrimenti il kill sotto farebbe scattare la gestione
+  // fallimento della generazione vecchia in corsa con quella nuova (doppio
+  // scheduleRetry/enterDegraded, `child` azzerato da sotto i piedi).
+  outgoing.removeAllListeners('error');
+  outgoing.removeAllListeners('close');
+  outgoing.once('exit', proceed);
+  try { outgoing.kill('SIGTERM'); } catch (_) { return proceed(); }
+  const killTimer = setTimeout(() => {
+    try { if (outgoing.exitCode == null) outgoing.kill('SIGKILL'); } catch (_) {}
+  }, 1500);
+  if (typeof killTimer.unref === 'function') killTimer.unref();
+}
+
 function run() {
+  if (stopping) return finish();
+  replaceChild(spawnGeneration);
+}
+
+function spawnGeneration() {
   if (stopping) return finish();
   if (!writeState('starting')) return stop();
   logEvent(`ssh attempt=${attempt + 1} starting`);
   let stderrTail = '';
+  let localChild;
   try {
-    child = spawn(sshBin, sshArgs, { stdio: ['ignore', 'inherit', 'pipe'] });
+    localChild = spawn(sshBin, sshArgs, { stdio: ['ignore', 'inherit', 'pipe'] });
   } catch (e) {
     child = null;
     return scheduleRetry(String(e && e.message || e));
   }
+  child = localChild;
 
-  child.stderr?.on('data', (chunk) => {
+  localChild.stderr?.on('data', (chunk) => {
     const text = String(chunk || '');
     stderrTail = `${stderrTail}${text}`.slice(-8192);
     try { process.stderr.write(chunk); } catch (_) {}
@@ -202,6 +432,12 @@ function run() {
   const handleFailure = (detail) => {
     if (failureHandled) return;
     failureHandled = true;
+    // Difesa in profondita', come probeForward: se replaceChild ha gia'
+    // sostituito questa generazione (i suoi listener sono stati distaccati,
+    // quindi in pratica questo ramo non dovrebbe piu' potersi attivare per
+    // una generazione rimpiazzata) non tocchiamo lo stato di una generazione
+    // che non e' piu' quella corrente.
+    if (child !== localChild) return;
     clearTimeout(upTimer);
     clearForwardProbe();
     child = null;
@@ -215,25 +451,26 @@ function run() {
     }
     scheduleRetry((diagnosis && diagnosis.detail) || detail);
   };
-  child.once('spawn', () => {
+  localChild.once('spawn', () => {
     logEvent(`ssh attempt=${attempt + 1} spawned`);
     // ExitOnForwardFailure only proves that the local bind was accepted. It
     // does not prove authentication or remote reachability, so after the
     // stability window require a real TCP open through the -L channel.
     upTimer = setTimeout(() => {
-      if (!stopping && child && child.exitCode == null) {
-        probeForward(child);
+      if (!stopping && child === localChild && localChild.exitCode == null) {
+        probeForward(localChild);
       }
     }, stableMs);
   });
-  child.once('error', (e) => {
+  localChild.once('error', (e) => {
     logEvent(`ssh child error code=${(e && e.code) || 'unknown'}`);
     handleFailure(String(e && e.message || e));
   });
   // `close` fires after stderr has drained, so classification sees the complete
   // OpenSSH diagnostic instead of racing the child `exit` event.
-  child.once('close', (code, signal) => {
+  localChild.once('close', (code, signal) => {
     if (stopping) return finish();
+    if (child !== localChild) return; // sostituita da replaceChild: gestita li', non qui
     logEvent(`ssh exited code=${code === null ? 'null' : code} signal=${signal || 'none'}`);
     handleFailure(`ssh exited code=${code} signal=${signal || ''}`);
   });
@@ -286,4 +523,8 @@ function acquireGeneration() {
   if (Date.now() >= ownershipDeadline) return finish();
   ownershipWaitTimer = setTimeout(acquireGeneration, 20);
 }
-acquireGeneration();
+if (require.main === module) acquireGeneration();
+
+// Esportate per prova diretta (R19): il main resta argv/env-driven e NON parte
+// al require.
+module.exports = { probeForwardChannels, refusalHint, refusalDetails, CHANNEL_GRACE_MS };