@mmmbuto/nexuscrew 0.8.7 → 0.8.10

package/lib/nodes/store.js

@@ -103,8 +103,8 @@ const LABEL_MAX = 64;
 // tollerato oltre a quelli noti (schema chiuso: garbage -> null, non guess).
 const NODE_KEYS = new Set([
   'name', 'ssh', 'sshPort', 'remotePort', 'localPort', 'keyPath', 'identityFile',
-  'roles', 'token', 'acceptToken', 'nodeId', 'transport', 'autostart', 'visibility', 'selected',
-  'direction', 'reversePort', 'label',
+  'roles', 'rolesKnown', 'token', 'acceptToken', 'nodeId', 'transport', 'autostart', 'visibility', 'selected',
+  'direction', 'reversePort', 'shared', 'label',
 ]);
 function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   if (!n || typeof n !== 'object' || Array.isArray(n)) return null;
@@ -123,6 +123,10 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   if (schemaVersion === LEGACY_SCHEMA_VERSION && !identityFile) return null;
   const roles = parseRoles(n.roles);
   if (!roles) return null;
+  if (n.rolesKnown !== undefined && typeof n.rolesKnown !== 'boolean') return null;
+  // Before 0.8.9 `roles` was filled with a local default and did not describe
+  // the remote peer. Only the explicit marker makes role-based health safe.
+  const rolesKnown = n.rolesKnown === true;
   // label (display) opzionale ma, se presente, strict: stringa 1..LABEL_MAX, no
   // control char (newline/tab inclusi: una label su piu' righe non ha senso in
   // UI), no solo-spazi. Garbage -> null (schema chiuso), mai guess/truncate.
@@ -140,15 +144,22 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     remotePort: n.remotePort,
     localPort: n.localPort,
     roles,
+    rolesKnown,
     direction,
     transport: n.transport || (direction === 'inbound' ? 'inbound' : (schemaVersion === LEGACY_SCHEMA_VERSION ? 'ssh' : 'auto')),
     autostart: n.autostart === undefined ? schemaVersion !== LEGACY_SCHEMA_VERSION : n.autostart,
+    // A paired device is private by default. `shared` only controls whether the
+    // hub may advertise/route this peer and whether the outbound SSH session
+    // requests the optional reverse (-R) channel. Old stores therefore migrate
+    // safely to private without a schema bump.
+    shared: n.shared === undefined ? false : n.shared,
     visibility: n.visibility || 'network',
   };
   if (!['auto', 'ssh', 'autossh', 'inbound'].includes(out.transport)) return null;
   if (direction === 'inbound' && out.transport !== 'inbound') return null;
   if (direction === 'outbound' && out.transport === 'inbound') return null;
   if (typeof out.autostart !== 'boolean') return null;
+  if (typeof out.shared !== 'boolean') return null;
   if (!['network', 'relay-only', 'selected'].includes(out.visibility)) return null;
   if (identityFile) out.identityFile = identityFile;
   // Keep the old public field while reading v1 so old callers/tests and a
@@ -183,7 +194,9 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   return out;
 }
 
-// rendezvous (ruolo node/reverse): dove questa installazione si pubblica.
+// Legacy rendezvous record: read-only migration data from pre-0.8.10. It is
+// parsed so an existing store remains loadable, but no new runtime path writes
+// or starts it.
 const RDV_KEYS = new Set(['ssh', 'publishedPort', 'localPort', 'keyPath']);
 function parseRendezvous(r) {
   if (!r || typeof r !== 'object' || Array.isArray(r)) return null;
@@ -357,18 +370,6 @@ function updateNode(store, name, patch) {
   return { ...store, schemaVersion: SCHEMA_VERSION, nodes };
 }
 
-function setRendezvous(store, rdv) {
-  const parsed = parseRendezvous(rdv);
-  if (!parsed) throw new Error('rendezvous non valido: controlla ssh/publishedPort/localPort/keyPath');
-  return { ...store, schemaVersion: SCHEMA_VERSION, rendezvous: parsed };
-}
-
-function clearRendezvous(store) {
-  const out = { ...store, schemaVersion: SCHEMA_VERSION };
-  delete out.rendezvous;
-  return out;
-}
-
 // --- Redazione (view sicura per status/list: MAI il token) ------------------
 
 function redactNode(n) {
@@ -379,8 +380,11 @@ function redactNode(n) {
     remotePort: n.remotePort,
     localPort: n.localPort,
     direction: n.direction || 'outbound',
+    roles: { ...n.roles },
+    rolesKnown: n.rolesKnown === true,
     transport: n.transport || 'ssh',
     autostart: !!n.autostart,
+    shared: n.shared === true,
     visibility: n.visibility || 'network',
     hasToken: !!n.token, // presenza, non il valore
     paired: !!(n.token && n.acceptToken),
@@ -398,11 +402,17 @@ function redactStore(store) {
     nodeId: store.nodeId,
     nodes: store.nodes.map(redactNode),
   };
-  // rendezvous non contiene token: sicuro da esporre integralmente.
-  if (store.rendezvous) out.rendezvous = { ...store.rendezvous };
   return out;
 }
 
+// A peer with both scoped credentials has completed pairing. Its advertised
+// HTTP port is part of the established SSH/federation contract; silently
+// moving that port would strand the peer even though the local PWA still works.
+function hasPairedPeers(store) {
+  return !!(store && Array.isArray(store.nodes)
+    && store.nodes.some((node) => validToken(node.token) && validToken(node.acceptToken)));
+}
+
 // --- Migrazione esplicita da config.json (guarded, no-op se assente) ---------
 // Se config.json contiene un array `nodes` legacy (vecchio formato pre-B0),
 // lo importa in nodes.json. Guarded: no-op se config.json non ha `nodes`, o se
@@ -486,13 +496,13 @@ function suggestNodeName(input, existing = []) {
 
 module.exports = {
   // parse/validate
-  parseStore, parseNode, parseRendezvous, parseSsh, parseSshTarget, isPort, isAbsPath, validToken,
+  parseStore, parseNode, parseRendezvous, parseRoles, parseSsh, parseSshTarget, isPort, isAbsPath, validToken,
   // I/O
   defaultNodesPath, loadStore, atomicWriteStore, loadOrInitStore, emptyStore, newNodeId,
   // mutazioni
-  getNode, addNode, removeNode, setNodeToken, updateNode, setRendezvous, clearRendezvous,
+  getNode, addNode, removeNode, setNodeToken, updateNode,
   // redazione
-  redactNode, redactStore,
+  redactNode, redactStore, hasPairedPeers,
   // migrazione
   migrateLegacyNodes,
   // label / slug

package/lib/nodes/tunnel-supervisor.js

@@ -10,7 +10,11 @@ const { backoffDelay } = require('./tunnel.js');
 const sshBin = process.argv[2];
 const sshArgs = process.argv.slice(3);
 const statePath = process.env.NEXUSCREW_TUNNEL_STATE;
-if (!sshBin || !statePath) process.exit(2);
+const pidPath = process.env.NEXUSCREW_TUNNEL_PIDFILE;
+const runId = process.env.NEXUSCREW_TUNNEL_RUN_ID;
+const stableMsRaw = Number(process.env.NEXUSCREW_TUNNEL_STABLE_MS || 3000);
+const stableMs = Number.isFinite(stableMsRaw) && stableMsRaw >= 100 ? Math.min(stableMsRaw, 30000) : 3000;
+if (!sshBin || !statePath || !pidPath || !runId) process.exit(2);
 
 let child = null;
 let stopping = false;
@@ -18,16 +22,26 @@ let attempt = 0;
 let retryTimer = null;
 let upTimer = null;
 
+function ownsGeneration() {
+  try {
+    const meta = JSON.parse(fs.readFileSync(pidPath, 'utf8'));
+    return meta && meta.pid === process.pid && meta.runId === runId;
+  } catch (_) { return false; }
+}
+
 function writeState(status, extra = {}) {
-  const tmp = `${statePath}.tmp.${process.pid}`;
-  const data = { status, supervisorPid: process.pid, attempt, updatedAt: Date.now(), ...extra };
+  if (!ownsGeneration()) return false;
+  const tmp = `${statePath}.tmp.${process.pid}.${runId}`;
+  const data = { status, runId, transport: path.basename(sshBin), supervisorPid: process.pid, attempt, updatedAt: Date.now(), ...extra };
   try {
     fs.mkdirSync(path.dirname(statePath), { recursive: true });
     fs.writeFileSync(tmp, `${JSON.stringify(data)}\n`, { mode: 0o600 });
     fs.chmodSync(tmp, 0o600);
     fs.renameSync(tmp, statePath);
+    return true;
   } catch (_) {
     try { fs.unlinkSync(tmp); } catch (_e) {}
+    return false;
   }
 }
 
@@ -58,14 +72,15 @@ function run() {
     scheduleRetry(detail);
   };
   child.once('spawn', () => {
-    // ExitOnForwardFailure makes bind/auth failures exit. Surviving this short
-    // grace window is the best portable readiness signal available for ssh -N.
+    // ExitOnForwardFailure makes bind/auth failures exit. Do not reset backoff
+    // or advertise readiness on the spawn event: only a stable transport window
+    // qualifies as transport-ready; HTTP federation health is checked above us.
     upTimer = setTimeout(() => {
       if (!stopping && child && child.exitCode == null) {
         attempt = 0;
-        writeState('up', { sshPid: child.pid });
+        writeState('transport-ready', { sshPid: child.pid, stableMs });
       }
-    }, 750);
+    }, stableMs);
   });
   child.once('error', (e) => {
     handleFailure(String(e && e.message || e));
@@ -79,8 +94,13 @@ function run() {
 function finish() {
   clearTimeout(retryTimer);
   clearTimeout(upTimer);
-  writeState('down');
-  try { fs.unlinkSync(statePath); } catch (_) {}
+  if (ownsGeneration()) {
+    writeState('down');
+    try {
+      const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+      if (state.runId === runId && state.supervisorPid === process.pid) fs.unlinkSync(statePath);
+    } catch (_) {}
+  }
   process.exit(0);
 }
 

package/lib/nodes/tunnel.js

@@ -1,12 +1,12 @@
 'use strict';
 // lib/nodes/tunnel.js — SSH tunnel manager (design §4b(1), §7).
 //
-// I processi ssh sono figli del lifecycle CLI/service, MAI di un handler HTTP
-// (nessun spawn dalla superficie web). Template SSH ESATTI dal design §4b(1);
-// argv puro (spawn con array), nessuna shell interpolation.
+// I processi ssh sono gestiti da un solo supervisor detached, avviato dal
+// lifecycle del servizio o dalle azioni PWA autenticate. argv puro (spawn con
+// array), nessuna shell interpolation.
 //
 // Due meccaniche:
-//   - builder puri (buildForwardArgs/buildReverseArgs) + backoff deterministico:
+//   - builder puro buildForwardArgs + backoff deterministico:
 //     unit-testabili senza lanciare ssh.
 //   - lifecycle per-tunnel via pidfile (start/stop/restart/state): il processo
 //     ssh e' detached, la sua liveness/porta stabile e' interrogabile da
@@ -16,6 +16,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const crypto = require('node:crypto');
 const { spawn, spawnSync } = require('node:child_process');
 const pidf = require('../cli/pidfile.js');
 const store = require('./store.js');
@@ -39,14 +40,6 @@ function assertForwardSpec(node) {
   if (!store.parseSshTarget(node.ssh)) throw new Error('tunnel: target ssh non valido');
 }
 
-function assertReverseSpec(rdv) {
-  if (!rdv || typeof rdv !== 'object') throw new Error('tunnel: rendezvous mancante');
-  if (!store.isPort(rdv.publishedPort)) throw new Error('tunnel: publishedPort non valida');
-  if (!store.isPort(rdv.localPort)) throw new Error('tunnel: localPort non valida');
-  if (!store.isAbsPath(rdv.keyPath)) throw new Error('tunnel: keyPath non valido');
-  if (!store.parseSsh(rdv.ssh)) throw new Error('tunnel: ssh (user@rendezvous) non valido');
-}
-
 // Forward client->nodo (ruolo client). §4b(1):
 //   ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30
 //       -o ServerAliveCountMax=3 -o BatchMode=yes -i <key>
@@ -55,9 +48,12 @@ function buildForwardArgs(node) {
   assertForwardSpec(node);
   const transport = node.sshPort === undefined ? [] : ['-p', String(node.sshPort)];
   const identity = node.identityFile || node.keyPath;
-  const reverse = node.reversePort === undefined ? [] : [
+  // The forward channel is the connection to the hub and is always present.
+  // The reverse channel publishes this device back through the hub, so it is
+  // opt-in only. A negotiated reversePort alone must never imply consent.
+  const reverse = node.shared === true && node.reversePort !== undefined ? [
     '-R', `127.0.0.1:${node.reversePort}:127.0.0.1:${node.localAppPort || node.remotePort}`,
-  ];
+  ] : [];
   return SSH_BASE_OPTS.concat(transport, identity ? ['-i', identity] : [], [
     '-L', `127.0.0.1:${node.localPort}:127.0.0.1:${node.remotePort}`,
     ...reverse,
@@ -65,18 +61,6 @@ function buildForwardArgs(node) {
   ]);
 }
 
-// Reverse nodo->rendezvous (ruolo node). §4b(1): bind loopback ESPLICITO lato
-// remoto (mai wildcard):
-//   ssh -N ... -i <key> -R 127.0.0.1:<pubblicata>:127.0.0.1:<locale> user@rendezvous
-function buildReverseArgs(rdv) {
-  assertReverseSpec(rdv);
-  return SSH_BASE_OPTS.concat([
-    '-i', rdv.keyPath,
-    '-R', `127.0.0.1:${rdv.publishedPort}:127.0.0.1:${rdv.localPort}`,
-    rdv.ssh,
-  ]);
-}
-
 // Backoff esponenziale + jitter (design §7). Deterministico con rng iniettato.
 //   delay = clamp(base * factor^attempt, 0..cap) * (1 +- jitter*(2*rand-1))
 // rng()=0.5 -> jitter nullo (ritorna il valore base clamperato); test deterministici.
@@ -98,8 +82,8 @@ function tunnelDir(home) {
   return path.join(home || os.homedir(), '.nexuscrew', 'tunnels');
 }
 
-// pidfile per-tunnel: forward "<name>", reverse "__rendezvous__". Il name e' gia'
-// una chiave strict (^[a-z0-9-]{1,32}$), safe come basename.
+// pidfile per-tunnel: forward "<name>". `__rendezvous__` è riconosciuto soltanto
+// per spegnere un supervisor legacy durante la migrazione.
 function tunnelPidPath(home, name) {
   return path.join(tunnelDir(home), `${name}.pid`);
 }
@@ -108,6 +92,95 @@ function tunnelLogPath(home, name) {
   return path.join(tunnelDir(home), `${name}.log`);
 }
 
+function prepareTunnelDir(home) {
+  const dir = tunnelDir(home);
+  try {
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) throw new Error('unsafe tunnel directory');
+    fs.chmodSync(dir, 0o700);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) throw new Error('unsafe tunnel directory');
+    fs.chmodSync(dir, 0o700);
+  }
+  return dir;
+}
+
+function openTunnelLog(home, name) {
+  prepareTunnelDir(home);
+  const logPath = tunnelLogPath(home, name);
+  const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC |
+    (fs.constants.O_NOFOLLOW || 0);
+  let fd;
+  try {
+    fd = fs.openSync(logPath, flags, 0o600);
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) throw new Error('unsafe tunnel log');
+    fs.fchmodSync(fd, 0o600);
+    return { fd, logPath };
+  } catch (error) {
+    if (fd !== undefined) try { fs.closeSync(fd); } catch (_) {}
+    throw error;
+  }
+}
+
+// Classifica soltanto firme SSH note e restituisce messaggi sicuri/azionabili:
+// mai rimandare il log grezzo alla PWA (può contenere host/path locali). Serve
+// soprattutto nel pairing: un normale `ssh hub-alias` può autenticarsi mentre permitopen nega
+// il forward richiesto, caso che prima collassava nel generico "fetch failed".
+function classifySshFailure(text, remotePort) {
+  const s = String(text || '');
+  const target = store.isPort(remotePort) ? `127.0.0.1:${remotePort}` : 'la porta NexusCrew richiesta';
+  if (/administratively prohibited|request (?:was )?denied|open failed:.*prohibited|port forwarding.*(?:disabled|denied)/i.test(s)) {
+    return {
+      code: 'forward-denied',
+      detail: `SSH autenticato, ma il server ha negato il port forwarding verso ${target}`,
+      hint: `verifica AllowTcpForwarding e l'eventuale permitopen per ${target}; il link NON e' stato consumato`,
+    };
+  }
+  if (/Permission denied \((?:publickey|password|keyboard-interactive)[^)]*\)|No supported authentication methods available/i.test(s)) {
+    return { code: 'ssh-auth-failed', detail: 'autenticazione SSH rifiutata', hint: 'verifica la chiave o l’Host SSH configurato su questo dispositivo; il link NON e\' stato consumato' };
+  }
+  if (/REMOTE HOST IDENTIFICATION HAS CHANGED|Host key verification failed|authenticity of host .* can'?t be established/i.test(s)) {
+    return { code: 'ssh-host-key', detail: 'verifica della host key SSH non completata', hint: 'verifica la host key con il normale client SSH; NexusCrew non la accetta automaticamente' };
+  }
+  if (/Could not resolve hostname|Name or service not known|nodename nor servname provided/i.test(s)) {
+    return { code: 'ssh-dns', detail: 'host SSH non risolvibile', hint: 'verifica hostname o alias nel file SSH di questo dispositivo' };
+  }
+  if (/Bad owner or permissions on .*ssh|Bad configuration option|Could not open user configuration file/i.test(s)) {
+    return { code: 'ssh-config', detail: 'configurazione SSH non utilizzabile', hint: 'verifica permessi e opzioni del file ~/.ssh/config' };
+  }
+  if (/remote port forwarding failed|Could not request remote forwarding/i.test(s)) {
+    return { code: 'reverse-forward-denied', detail: 'il server SSH ha negato il canale inverso del nodo', hint: 'verifica permitlisten/AllowTcpForwarding sul nodo hub' };
+  }
+  if (/Could not request local forwarding|Address already in use/i.test(s)) {
+    return { code: 'local-forward-bind', detail: 'la porta locale scelta per il tunnel non è disponibile', hint: 'ferma il tunnel precedente e riprova' };
+  }
+  if (/Connection refused|No route to host|Connection timed out|Operation timed out|Network is unreachable/i.test(s)) {
+    return { code: 'ssh-unreachable', detail: 'endpoint SSH non raggiungibile', hint: 'verifica rete, hostname e porta SSH' };
+  }
+  return null;
+}
+
+function readTunnelDiagnostic(home, name, remotePort) {
+  if (!store.NODE_NAME_RE.test(String(name || ''))) return null;
+  const p = tunnelLogPath(home, name);
+  let fd;
+  try {
+    fd = fs.openSync(p, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) return null;
+    const size = Math.min(st.size, 16 * 1024);
+    if (!size) return null;
+    const buf = Buffer.alloc(size);
+    fs.readSync(fd, buf, 0, size, Math.max(0, st.size - size));
+    return classifySshFailure(buf.toString('utf8'), remotePort);
+  } catch (_) { return null; }
+  finally { if (fd !== undefined) try { fs.closeSync(fd); } catch (_) {} }
+}
+
 function tunnelStatePath(home, name) {
   return path.join(tunnelDir(home), `${name}.state.json`);
 }
@@ -119,8 +192,16 @@ function readTunnelState(home, name) {
   if (meta && pidf.isAlive(meta)) {
     try {
       const state = JSON.parse(fs.readFileSync(tunnelStatePath(home, name), 'utf8'));
-      if (state.status === 'up') return { status: 'up', pid: meta.pid, since: meta.startTs || null };
-      return { status: 'down', pid: meta.pid, since: meta.startTs || null, reason: state.status || 'starting' };
+      const transport = typeof state.transport === 'string' ? state.transport : undefined;
+      const owned = state.supervisorPid === meta.pid && (!meta.runId || state.runId === meta.runId);
+      if (!owned) return { status: 'down', pid: meta.pid, since: meta.startTs || null, reason: 'starting' };
+      if (state.status === 'transport-ready' || state.status === 'up') {
+        return { status: 'up', phase: 'transport-ready', pid: meta.pid, since: meta.startTs || null,
+          ...(Number.isInteger(state.attempt) ? { attempt: state.attempt } : {}), ...(transport ? { transport } : {}) };
+      }
+      return { status: 'down', phase: state.status || 'starting', pid: meta.pid, since: meta.startTs || null,
+        reason: state.status || 'starting', ...(Number.isInteger(state.attempt) ? { attempt: state.attempt } : {}),
+        ...(Number.isFinite(state.delayMs) ? { retryInMs: state.delayMs } : {}), ...(transport ? { transport } : {}) };
     } catch (_) {
       // Backward compatibility for pre-supervisor pidfiles: a live direct ssh
       // process had no state sidecar and was considered up.
@@ -133,6 +214,50 @@ function readTunnelState(home, name) {
   return { status: 'down' };
 }
 
+function diagnoseTunnel(home, node, state = null) {
+  const current = state || readTunnelState(home, node && node.name);
+  const ssh = node && readTunnelDiagnostic(home, node.name, node.remotePort);
+  if (ssh) return { stage: 'ssh', ...ssh, status: current.status, phase: current.phase || current.reason || null };
+  if (current.status === 'up') {
+    return { stage: 'transport', code: 'transport-ready', status: 'up', phase: current.phase || 'transport-ready',
+      detail: 'trasporto SSH stabile; verifica federation in corso' };
+  }
+  if (current.reason === 'starting' || current.phase === 'starting') {
+    return { stage: 'ssh', code: 'ssh-starting', status: 'starting', phase: 'starting',
+      detail: 'connessione SSH in avvio', hint: 'attendi qualche secondo e usa Test connessione' };
+  }
+  if (current.reason === 'retrying' || current.phase === 'retrying') {
+    return { stage: 'ssh', code: 'ssh-retrying', status: 'retrying', phase: 'retrying',
+      detail: `connessione SSH in retry${Number.isInteger(current.attempt) ? ` (tentativo ${current.attempt + 1})` : ''}`,
+      hint: 'usa Test connessione per vedere la causa; verifica target SSH, chiave e porta' };
+  }
+  return { stage: 'ssh', code: 'tunnel-stopped', status: 'down', phase: current.phase || null,
+    detail: 'connessione SSH ferma', hint: 'avvia la connessione dalla PWA, Impostazioni > Nodi' };
+}
+
+function removeStateIfOwned(home, name, meta) {
+  const statePath = tunnelStatePath(home, name);
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    const samePid = !meta || !meta.pid || state.supervisorPid === meta.pid;
+    const sameRun = !meta || !meta.runId || state.runId === meta.runId;
+    if (samePid && sameRun) { fs.unlinkSync(statePath); return true; }
+  } catch (_) {}
+  return false;
+}
+
+function supervisorExited(pid, timeoutMs = 2500) {
+  const deadline = Date.now() + timeoutMs;
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  const exited = () => {
+    if (!pidf.pidExists(pid)) return true;
+    try { return fs.readFileSync(`/proc/${pid}/stat`, 'utf8').split(' ')[2] === 'Z'; }
+    catch (_) { return false; }
+  };
+  while (!exited() && Date.now() < deadline) Atomics.wait(sleeper, 0, 0, 25);
+  return exited();
+}
+
 // Pre-flight sincrono: l'unico modo di "surfaccare" un binario ssh assente come
 // failure ESPLICITA nel valore di ritorno (lo spawn emette 'error' asincrono, non
 // catturabile sync). spawnSyncImpl iniettabile per test deterministici.
@@ -167,19 +292,40 @@ function startTunnel(opts) {
   if (!Array.isArray(args)) throw new Error('startTunnel: args mancanti');
 
   const pidPath = tunnelPidPath(home, name);
+  const supervisor = path.join(__dirname, 'tunnel-supervisor.js');
+  const runId = crypto.randomBytes(16).toString('hex');
+  const supervisorArgs = [supervisor, sshBin, ...args];
+  const cmd = `${process.execPath} ${supervisorArgs.join(' ')}`;
   const existing = pidf.readPidfile(pidPath);
   if (existing && pidf.isAlive(existing)) {
-    return { started: false, reason: 'already running', pid: existing.pid };
+    // An update or automatic HTTP-port fallback can change -L/-R while the
+    // detached supervisor is still alive.  Keep exact matches idempotent, but
+    // replace a supervisor whose saved argv no longer matches the desired one.
+    if (!existing.cmd || existing.cmd === cmd) {
+      return { started: false, reason: 'already running', pid: existing.pid, transport: sshBin };
+    }
+    const oldMeta = existing;
+    const stopped = pidf.killPidfile(pidPath);
+    if (!stopped.killed) return { started: false, reason: `running spec mismatch: ${stopped.reason || 'stop failed'}`, pid: existing.pid };
+    if (!(opts.supervisorExitedImpl || supervisorExited)(oldMeta.pid, opts.stopWaitMs || 2500)) {
+      return { started: false, reason: `running spec mismatch: old supervisor ${oldMeta.pid} did not exit`, pid: oldMeta.pid };
+    }
+    removeStateIfOwned(home, name, oldMeta);
   }
   pidf.cleanStale(pidPath);
 
-  fs.mkdirSync(tunnelDir(home), { recursive: true });
   const logPath = tunnelLogPath(home, name);
   const statePath = tunnelStatePath(home, name);
   // fdProvided: il caller ci passa un fd (es. test con logFd:null) e ne rimane
   // proprietario; noi chiudiamo solo la fd che apriamo noi (no double-close).
   const fdProvided = opts.logFd !== undefined;
-  const logFd = fdProvided ? opts.logFd : fs.openSync(logPath, 'a');
+  let logFd;
+  try {
+    prepareTunnelDir(home);
+    logFd = fdProvided ? opts.logFd : openTunnelLog(home, name).fd;
+  } catch (_) {
+    return { started: false, reason: 'unsafe tunnel log path' };
+  }
   let fdClosed = false;
   const closeOwnedFd = () => {
     if (fdClosed) return; fdClosed = true;
@@ -196,13 +342,17 @@ function startTunnel(opts) {
   // Spawn a detached Node supervisor. It owns ssh and retries failures with the
   // bounded backoff defined above, so CLI/server lifetime does not own liveness.
   let child;
-  const supervisor = path.join(__dirname, 'tunnel-supervisor.js');
-  const supervisorArgs = [supervisor, sshBin, ...args];
   try {
     child = spawnImpl(process.execPath, supervisorArgs, {
       detached: true,
       stdio: ['ignore', logFd, logFd],
-      env: { ...process.env, AUTOSSH_GATETIME: '0', NEXUSCREW_TUNNEL_STATE: statePath },
+      env: {
+        ...process.env,
+        NEXUSCREW_TUNNEL_STATE: statePath,
+        NEXUSCREW_TUNNEL_PIDFILE: pidPath,
+        NEXUSCREW_TUNNEL_RUN_ID: runId,
+        ...(opts.stableMs === undefined ? {} : { NEXUSCREW_TUNNEL_STABLE_MS: String(opts.stableMs) }),
+      },
     });
   } catch (e) {
     closeOwnedFd();
@@ -216,8 +366,8 @@ function startTunnel(opts) {
   let pid = child && child.pid;
   const cleanupIfOwned = () => {
     const current = pidf.readPidfile(pidPath);
-    if (current && current.pid === pid) pidf.removePidfile(pidPath);
-    try { fs.unlinkSync(statePath); } catch (_) {}
+    if (current && current.pid === pid && current.runId === runId) pidf.removePidfile(pidPath);
+    removeStateIfOwned(home, name, { pid, runId });
   };
   if (child && typeof child.on === 'function') {
     child.on('error', () => {
@@ -232,10 +382,9 @@ function startTunnel(opts) {
     return { started: false, reason: 'spawn error (no pid)' };
   }
 
-  const cmd = `${process.execPath} ${supervisorArgs.join(' ')}`;
   // writePidfile e' exclusive (wx): cleanStale sopra ha gia' tolto uno stale.
   try {
-    pidf.writePidfile(pidPath, pid, cmd);
+    pidf.writePidfile(pidPath, pid, cmd, { runId });
   } catch (e) {
     try { process.kill(pid, 'SIGTERM'); } catch (_) {}
     cleanupIfOwned();
@@ -243,7 +392,7 @@ function startTunnel(opts) {
     return { started: false, reason: 'pidfile error', error: String(e && e.message || e) };
   }
   closeOwnedFd(); // copia del padre: il figlio ha la sua dup; nessun leak (audit F3)
-  return { started: true, pid, logPath };
+  return { started: true, pid, logPath, transport: sshBin };
 }
 
 // Ferma il tunnel: kill verificato via pidfile (mai broad match by name).
@@ -251,8 +400,13 @@ function stopTunnel(opts) {
   const home = opts.home || os.homedir();
   const name = opts.name;
   if (!name) throw new Error('stopTunnel: name mancante');
-  const r = pidf.killPidfile(tunnelPidPath(home, name));
-  try { fs.unlinkSync(tunnelStatePath(home, name)); } catch (_) {}
+  const pidPath = tunnelPidPath(home, name);
+  const meta = pidf.readPidfile(pidPath);
+  const r = pidf.killPidfile(pidPath);
+  if (r.killed && !(opts.supervisorExitedImpl || supervisorExited)(r.pid, opts.stopWaitMs || 2500)) {
+    return { stopped: false, pid: r.pid, reason: `supervisor ${r.pid} did not exit after SIGTERM` };
+  }
+  removeStateIfOwned(home, name, meta);
   return { stopped: r.killed, pid: r.pid, reason: r.reason };
 }
 
@@ -264,29 +418,24 @@ function restartTunnel(opts) {
 // Helper di alto livello: costruisce args dal nodo e avvia il forward.
 function startForward(opts) {
   const node = opts.node;
-  let sshBin = opts.sshBin;
-  let args = buildForwardArgs({ ...node, localAppPort: opts.localAppPort });
-  const wanted = node.transport || (node.keyPath ? 'ssh' : 'auto');
-  if (!sshBin && (wanted === 'auto' || wanted === 'autossh') && sshBinaryAvailable('autossh', opts.spawnSyncImpl)) {
-    sshBin = 'autossh';
-    args = ['-M', '0', ...args];
-  } else if (!sshBin) {
-    sshBin = 'ssh';
-  }
+  const args = buildForwardArgs({ ...node, localAppPort: opts.localAppPort });
+  // NexusCrew already owns retry/backoff in tunnel-supervisor.js. Nesting
+  // autossh inside that supervisor made liveness dishonest: autossh could stay
+  // alive while every SSH child exited 255, so the UI reported "tunnel up".
+  // Use one portable supervisor around OpenSSH on Linux, macOS and Termux.
+  // `transport: autossh` remains readable for old stores but is normalized at
+  // runtime to supervised ssh.
+  const sshBin = opts.sshBin || 'ssh';
   return startTunnel({ ...opts, sshBin, name: node.name, args });
 }
 
-// Helper di alto livello: reverse verso il rendezvous.
+// Cleanup identifier for pre-0.8.10 standalone rendezvous supervisors. New
+// runtimes never start this second connection; stop/restart can still remove a
+// stale legacy process during migration.
 const REVERSE_NAME = '__rendezvous__';
-function startReverse(opts) {
-  const args = buildReverseArgs(opts.rendezvous);
-  return startTunnel({ ...opts, name: REVERSE_NAME, args });
-}
 
-// --- Capability OpenSSH (permitlisten, design §7 advisory (a)) --------------
-// permitlisten (vincola i -R) esiste da OpenSSH 7.8. Serve sul rendezvous per il
-// ruolo node; il check locale su `ssh -V` e' l'unico verificabile in autonomia.
-// null = versione non determinabile (non un fail: warn + verifica manuale).
+// Versione client OpenSSH, solo diagnostica. Non inferire mai da questa la
+// policy `permitlisten` del server remoto: quella si prova con il vero -R.
 function readSshVersion(spawnSyncImpl) {
   try {
     const r = (spawnSyncImpl || spawnSync)('ssh', ['-V'], { encoding: 'utf8' });
@@ -297,19 +446,15 @@ function readSshVersion(spawnSyncImpl) {
   } catch (_) { return null; }
 }
 
-// true/false se determinabile, null se versione ignota.
-function sshSupportsPermitlisten(v) {
-  if (!v) return null;
-  if (v.major > 7) return true;
-  if (v.major === 7 && v.minor >= 8) return true;
-  return false;
-}
-
 module.exports = {
   SSH_BASE_OPTS,
-  buildForwardArgs, buildReverseArgs, backoffDelay,
+  buildForwardArgs, backoffDelay,
   tunnelDir, tunnelPidPath, tunnelLogPath, tunnelStatePath, readTunnelState,
-  startTunnel, stopTunnel, restartTunnel, startForward, startReverse,
+  prepareTunnelDir, openTunnelLog,
+  classifySshFailure, readTunnelDiagnostic,
+  diagnoseTunnel,
+  removeStateIfOwned, supervisorExited,
+  startTunnel, stopTunnel, restartTunnel, startForward,
   REVERSE_NAME,
-  readSshVersion, sshSupportsPermitlisten, sshBinaryAvailable,
+  readSshVersion, sshBinaryAvailable,
 };