@mmmbuto/nexuscrew 0.8.9 → 0.8.10

package/lib/fleet/builtin.js

@@ -371,6 +371,17 @@ async function createBuiltinFleet(cfg = {}) {
       throw httpError(/duplicate/i.test(launch.stderr) ? 409 : 500, why);
     }
 
+    // `tmux new-session -d` can return 0 even when the launched CLI exits a
+    // moment later (missing login, bad model, incompatible provider).  Without
+    // this readiness gate the PWA reported success and then showed nothing.
+    // Always verify liveness, including cells without a system prompt.
+    const readyMs = cfg.launchReadyMs != null ? cfg.launchReadyMs : 500;
+    const alive = await waitAlive(tmuxBin, cell.tmuxSession, { env: minimalEnv(), readyMs });
+    if (!alive) {
+      cache = { ...cache, at: 0 };
+      throw httpError(500, `client ${launchEngine.command} terminato subito: verifica login, provider, modello e argomenti dell'engine`);
+    }
+
     // (6) prompt send-keys: bracketed-paste best-effort, target = pane id esatto
     // (fallback al nome sessione con match esatto '=' se tmux non ha stampato l'id).
     let prompt = null;
@@ -379,7 +390,7 @@ async function createBuiltinFleet(cfg = {}) {
       const target = paneId.startsWith('%') ? paneId : `=${cell.tmuxSession}`;
       prompt = await injectPrompt(tmuxBin, cell.tmuxSession, cell.prompt, {
         env: minimalEnv(),
-        readyMs: cfg.sendKeysReadyMs != null ? cfg.sendKeysReadyMs : 400,
+        readyMs: cfg.sendKeysReadyMs != null ? cfg.sendKeysReadyMs : readyMs,
         target,
         engine: launchEngine, cell, // per la redazione del reason se paste-buffer fallisce (§9h)
       });

package/lib/mcp/server.js

@@ -71,6 +71,79 @@ function requireSession(session, tool) {
   );
 }
 
+// Deck layout is stored column-major, while the UI is read row-major. Preserve
+// the visual order so an agent sees the same neighbourhood as the operator.
+function orderedDeckMembers(deck) {
+  const columns = deck && deck.layout && Array.isArray(deck.layout.columns)
+    ? deck.layout.columns : [];
+  const rows = Math.max(0, ...columns.map((column) => (
+    column && Array.isArray(column.tiles) ? column.tiles.length : 0
+  )));
+  const out = [];
+  for (let row = 0; row < rows; row += 1) {
+    for (const column of columns) {
+      const tile = column && Array.isArray(column.tiles) ? column.tiles[row] : null;
+      if (!tile || typeof tile.session !== 'string' || !tile.session) continue;
+      const member = { tmuxSession: tile.session };
+      if (typeof tile.node === 'string' && tile.node) member.node = tile.node;
+      if (typeof tile.ownerId === 'string' && NODE_ID_RE.test(tile.ownerId)) member.ownerId = tile.ownerId;
+      out.push(member);
+    }
+  }
+  return out;
+}
+
+const NODE_PART_RE = /^[a-z0-9-]{1,32}$/;
+const NODE_ID_RE = /^[a-f0-9]{16,64}$/;
+function fleetStatusPath(node) {
+  if (!node) return '/api/fleet/status';
+  const parts = String(node).split('/');
+  if (!parts.length || parts.some((part) => !NODE_PART_RE.test(part))
+    || new Set(parts).size !== parts.length) return null;
+  return `/api/route/${parts.map(encodeURIComponent).join('/')}/_/fleet/status`;
+}
+
+function fleetCellsBySession(payload) {
+  const out = new Map();
+  if (!payload || payload.available !== true || !Array.isArray(payload.cells)) return out;
+  for (const cell of payload.cells) {
+    if (!cell || typeof cell.tmuxSession !== 'string' || !cell.tmuxSession
+      || typeof cell.cell !== 'string' || !cell.cell) continue;
+    out.set(cell.tmuxSession, cell.cell);
+  }
+  return out;
+}
+
+function routePath(route, resource) {
+  if (!Array.isArray(route) || !route.length || route.length > 4
+    || route.some((part) => !NODE_PART_RE.test(part)) || new Set(route).size !== route.length) return null;
+  return `/api/route/${route.map(encodeURIComponent).join('/')}/_/${resource}`;
+}
+
+function topologyOwners(payload) {
+  const out = [];
+  const seen = new Set();
+  for (const node of (payload && Array.isArray(payload.nodes) ? payload.nodes : [])) {
+    if (!node || !NODE_ID_RE.test(String(node.instanceId || '')) || seen.has(node.instanceId)
+      || !Array.isArray(node.route) || !routePath(node.route, 'decks')) continue;
+    seen.add(node.instanceId);
+    out.push({
+      instanceId: node.instanceId,
+      route: [...node.route],
+      label: typeof node.label === 'string' && node.label ? node.label : (node.name || node.route.join(' › ')),
+      stale: node.stale === true,
+    });
+  }
+  return out;
+}
+
+function memberOwnerId(member, deckOwner, ownerTopology) {
+  if (member.ownerId && NODE_ID_RE.test(member.ownerId)) return member.ownerId;
+  if (!member.node) return deckOwner.instanceId;
+  const found = ownerTopology.find((node) => Array.isArray(node.route) && node.route.join('/') === member.node);
+  return found ? found.instanceId : null;
+}
+
 // --- definizione tool (prefisso nc_ anti-collisione) ---------------------------
 // annotations.readOnlyHint:true sui tool che non mutano nulla (§1).
 const TOOLS = [
@@ -176,6 +249,94 @@ const TOOLS = [
       return { sessions, fleet };
     },
   },
+  {
+    name: 'nc_deck',
+    description: 'Contesto read-only del deck della sessione chiamante: restituisce i deck che la contengono e i relativi membri con nome cella Fleet, sessione tmux e route.',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { readOnlyHint: true },
+    async handler(_args, ctx) {
+      const tmuxSession = requireSession(await ctx.session(), 'nc_deck');
+      const [config, topology, localDecks] = await Promise.all([
+        ctx.api('GET', '/api/config'), ctx.api('GET', '/api/topology'), ctx.api('GET', '/api/decks'),
+      ]);
+      const localNodeId = String(config && config.instanceId || '');
+      if (!NODE_ID_RE.test(localNodeId)) throw new Error('instanceId locale non disponibile');
+      if (!localDecks || !Array.isArray(localDecks.decks)) throw new Error('risposta deck non valida');
+
+      const remotes = topologyOwners(topology).filter((owner) => !owner.stale && owner.instanceId !== localNodeId);
+      const viewerById = new Map([[localNodeId, []], ...remotes.map((owner) => [owner.instanceId, owner.route])]);
+      const sources = [{
+        owner: { instanceId: localNodeId, route: [], label: 'Local' },
+        ownerTopology: topologyOwners(topology), decks: localDecks.decks,
+      }];
+      await Promise.all(remotes.map(async (owner) => {
+        const decksPath = routePath(owner.route, 'decks');
+        const topologyPath = routePath(owner.route, 'topology');
+        if (!decksPath || !topologyPath) return;
+        try {
+          const [deckPayload, ownerTopology] = await Promise.all([
+            ctx.api('GET', decksPath), ctx.api('GET', topologyPath).catch(() => ({ nodes: [] })),
+          ]);
+          if (deckPayload && Array.isArray(deckPayload.decks)) {
+            sources.push({ owner, ownerTopology: topologyOwners(ownerTopology), decks: deckPayload.decks });
+          }
+        } catch (_) { /* owner offline/withdrawn: no stale deck disclosure */ }
+      }));
+
+      const decks = [];
+      for (const source of sources) {
+        for (const deck of source.decks) {
+          if (!deck || typeof deck.name !== 'string') continue;
+          const members = orderedDeckMembers(deck).map((member) => ({
+            ...member,
+            ownerId: memberOwnerId(member, source.owner, source.ownerTopology),
+          }));
+          if (!members.some((member) => member.ownerId === localNodeId && member.tmuxSession === tmuxSession)) continue;
+          decks.push({
+            id: `${source.owner.instanceId}:${deck.name}`,
+            name: deck.name,
+            owner: { instanceId: source.owner.instanceId, route: source.owner.route.length ? source.owner.route.join('/') : 'local', label: source.owner.label },
+            members,
+          });
+        }
+      }
+      decks.sort((a, b) => a.owner.route.localeCompare(b.owner.route) || a.name.localeCompare(b.name));
+
+      if (!decks.length) return { tmuxSession, nodeId: localNodeId, decks: [] };
+
+      const routes = new Set(['']);
+      for (const deck of decks) for (const member of deck.members) {
+        const route = member.ownerId && viewerById.has(member.ownerId)
+          ? viewerById.get(member.ownerId).join('/') : null;
+        member.viewerRoute = route;
+        if (route !== null) routes.add(route);
+      }
+      const cellsByRoute = new Map();
+      await Promise.all([...routes].map(async (route) => {
+        const apiPath = fleetStatusPath(route);
+        if (!apiPath) return;
+        try { cellsByRoute.set(route, fleetCellsBySession(await ctx.api('GET', apiPath))); }
+        catch (_) { cellsByRoute.set(route, new Map()); }
+      }));
+
+      return {
+        tmuxSession, nodeId: localNodeId,
+        decks: decks.map((deck) => ({
+          id: deck.id, name: deck.name, owner: deck.owner,
+          members: deck.members.map((member) => {
+            const route = member.viewerRoute;
+            return {
+              cell: route === null ? null : (cellsByRoute.get(route)?.get(member.tmuxSession) || null),
+              tmuxSession: member.tmuxSession,
+              ownerId: member.ownerId,
+              route: route === null ? 'unavailable' : (route || 'local'),
+              self: member.ownerId === localNodeId && member.tmuxSession === tmuxSession,
+            };
+          }),
+        })),
+      };
+    },
+  },
   {
     name: 'nc_inbox',
     description: 'Elenca i file ricevuti nell\'inbox NexusCrew di questa sessione (read-only).',

package/lib/nodes/commands.js

@@ -1,20 +1,22 @@
 'use strict';
-// lib/nodes/commands.js — subcomandi CLI `nodes` e `node` (design §3, §4, §4b).
+// lib/nodes/commands.js — implementation helpers for the authenticated PWA.
 //
-// nodes add/list/remove/test/up/down/restart/set-token + node on/off.
+// Nodes add/list/remove/test/up/down/restart/set-token. These helpers are not
+// advertised as public CLI commands.
 // Invarianti:
 //   - token per-nodo MAI loggati/stampati (redazione sempre; set-token li legge
 //     da stdin/env, mai da argv -> niente segreti in `ps`).
 //   - NEXUSCREW_READONLY blocca le MUTAZIONI DI CONFIG (add/remove/set-token/
-//     on/off), non list/test/status/up/down/restart (lifecycle tunnel, non config).
+//     configuration), while the Settings routes separately gate process lifecycle.
 //   - niente shell interpolation: ssh-keygen via execFile (argv), tunnel via spawn argv.
 const fs = require('node:fs');
+const net = require('node:net');
 const os = require('node:os');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const store = require('./store.js');
 const tunnel = require('./tunnel.js');
-const { resolvePaths, loadPort, DEFAULT_PORT } = require('../cli/url.js');
+const { resolvePaths, DEFAULT_PORT } = require('../cli/url.js');
 
 const LOCAL_PORT_BASE = 43001; // porte locali stabili per i forward (design: stabili da nodes.json)
 
@@ -38,6 +40,49 @@ function assignLocalPort(st) {
   return p;
 }
 
+function bindLocalPort(port, createServerImpl = net.createServer) {
+  return new Promise((resolve, reject) => {
+    const server = createServerImpl();
+    const onError = (error) => {
+      server.removeListener('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.removeListener('error', onError);
+      if (typeof server.unref === 'function') server.unref();
+      let released = false;
+      resolve({
+        port,
+        release: () => new Promise((done) => {
+          if (released) return done();
+          released = true;
+          try { server.close(() => done()); } catch (_) { done(); }
+        }),
+      });
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen({ host: '127.0.0.1', port, exclusive: true });
+  });
+}
+
+// Selezione OS-aware per il pairing: nodes.json evita collisioni logiche, il
+// bind reale evita porte gia' occupate da processi estranei. La socket resta
+// riservata fino all'avvio del supervisor SSH e viene poi rilasciata una volta.
+async function reserveLocalPort(st, opts = {}) {
+  const used = new Set((st.nodes || []).map((n) => n.localPort));
+  const createServerImpl = opts.createServerImpl || net.createServer;
+  for (let port = opts.start || LOCAL_PORT_BASE; port <= 65535; port += 1) {
+    if (used.has(port)) continue;
+    try { return await bindLocalPort(port, createServerImpl); }
+    catch (error) {
+      if (error && (error.code === 'EADDRINUSE' || error.code === 'EACCES')) continue;
+      throw error;
+    }
+  }
+  throw new Error('nessuna porta locale disponibile per il tunnel');
+}
+
 function defaultKeyPath(home, name) {
   return path.join(home, '.nexuscrew', 'keys', `${name}_ed25519`);
 }
@@ -59,24 +104,6 @@ function ensureKey(keyPath, name, opts = {}) {
   return fs.readFileSync(pubPath, 'utf8').trim();
 }
 
-// Scrittura atomica di config.json preservando il resto (per roles).
-function writeConfigRole(configPath, key, value) {
-  let cfg = {};
-  try { const c = JSON.parse(fs.readFileSync(configPath, 'utf8')); if (c && typeof c === 'object') cfg = c; } catch (_) {}
-  const roles = (cfg.roles && typeof cfg.roles === 'object') ? cfg.roles : {};
-  cfg.roles = { client: !!roles.client, node: !!roles.node };
-  cfg.roles[key] = value;
-  const dir = path.dirname(configPath);
-  fs.mkdirSync(dir, { recursive: true });
-  const tmp = path.join(dir, `.${path.basename(configPath)}.${process.pid}.tmp`);
-  try {
-    fs.writeFileSync(tmp, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 });
-    fs.chmodSync(tmp, 0o600);
-    fs.renameSync(tmp, configPath);
-  } catch (e) { try { fs.unlinkSync(tmp); } catch (_) {} throw e; }
-  return cfg.roles;
-}
-
 // Legge il token remoto da fonte NON-argv: opts.token (test) > env > stdin.
 // MAI da flag CLI: il token comparirebbe in `ps`/history.
 function readSecretToken(opts) {
@@ -93,7 +120,7 @@ function nodesAdd(opts) {
   const { home, nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
   const ssh = opts.ssh;
-  if (!name) { log('usage: nexuscrew nodes add <name> --ssh user@host [--ssh-port N] [--remote-port N] [--key path] [--local-port N]'); return { code: 1, reason: 'name mancante' }; }
+  if (!name) { log('nodes add: name mancante (configura il nodo dalla PWA)'); return { code: 1, reason: 'name mancante' }; }
   if (!ssh) { log('nodes add: --ssh user@host obbligatorio'); return { code: 1, reason: 'ssh mancante' }; }
 
   const remotePort = opts.remotePort ? Number(opts.remotePort) : DEFAULT_PORT;
@@ -159,7 +186,6 @@ function nodesList(opts) {
   const view = store.redactStore(st); // MAI il token
   const nodes = view.nodes.map((n) => ({ ...n, tunnel: tunnel.readTunnelState(home, n.name) }));
   const out = { nodeId: view.nodeId, nodes };
-  if (view.rendezvous) out.rendezvous = view.rendezvous;
 
   if (opts.json) { log(JSON.stringify(out, null, 2)); return { code: 0, nodes }; }
   if (nodes.length === 0) { log('nodes: (nessun nodo)'); return { code: 0, nodes }; }
@@ -175,7 +201,7 @@ function nodesRemove(opts) {
   if (isReadonly(opts)) { log('nodes remove: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
   const { home, nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes remove <name>'); return { code: 1 }; }
+  if (!name) { log('nodes remove: name mancante'); return { code: 1 }; }
   const st = store.loadStore(nodesPath);
   if (!st) { log('nodes remove: nessun nodes.json valido'); return { code: 1 }; }
   let next;
@@ -207,15 +233,16 @@ async function nodesTest(opts) {
   const log = opts.log || console.log;
   const { home, nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes test <name>'); return { code: 1 }; }
+  if (!name) { log('nodes test: name mancante'); return { code: 1 }; }
   const st = store.loadStore(nodesPath);
   const node = st ? store.getNode(st, name) : null;
   if (!node) { log(`nodes test: nodo sconosciuto "${name}"`); return { code: 1, result: 'unknown-node' }; }
 
   const state = tunnel.readTunnelState(home, name);
   if (state.status !== 'up') {
-    log(`nodes test [${name}]: TUNNEL DOWN — avvia con \`nexuscrew nodes up ${name}\``);
-    return { code: 1, result: 'tunnel-down' };
+    const diagnostic = tunnel.diagnoseTunnel(home, node, state);
+    log(`nodes test [${name}]: ${diagnostic.code.toUpperCase()} — ${diagnostic.detail}${diagnostic.hint ? ` · ${diagnostic.hint}` : ''}`);
+    return { code: 1, result: 'tunnel-down', diagnostic };
   }
 
   const httpProbe = opts.httpProbe || defaultHttpProbe;
@@ -226,13 +253,17 @@ async function nodesTest(opts) {
   try { health = await httpProbe(`${base}/`, {}); }
   catch (e) { health = { ok: false, error: e && e.message }; }
   if (!health || !health.ok) {
-    log(`nodes test [${name}]: HEALTH KO — tunnel up ma il server remoto non risponde (${(health && health.error) || 'no 2xx'})`);
-    return { code: 1, result: 'health-ko' };
+    const diagnostic = tunnel.diagnoseTunnel(home, node);
+    const realCause = diagnostic.code !== 'transport-ready' ? diagnostic.detail : ((health && health.error) || 'server HTTP non raggiungibile');
+    log(`nodes test [${name}]: HEALTH KO — ${realCause}${diagnostic.hint ? ` · ${diagnostic.hint}` : ''}`);
+    return { code: 1, result: 'health-ko', diagnostic: diagnostic.code === 'transport-ready'
+      ? { stage: 'http', code: 'peer-http-unreachable', detail: realCause, hint: 'verifica la porta NexusCrew contenuta nel link' }
+      : diagnostic };
   }
 
   // token: GET /api/config con Bearer del nodo -> 200 ok, 401 token KO.
   if (!node.token) {
-    log(`nodes test [${name}]: TOKEN ASSENTE — salva il token remoto con \`nexuscrew nodes set-token ${name}\``);
+    log(`nodes test [${name}]: ASSOCIAZIONE INCOMPLETA — rimuovi il nodo e ripeti il pairing dalla PWA`);
     return { code: 1, result: 'token-missing' };
   }
   let authed;
@@ -242,7 +273,7 @@ async function nodesTest(opts) {
     log(`nodes test [${name}]: OK — tunnel up, health ok, token valido`);
     return { code: 0, result: 'ok' };
   }
-  log(`nodes test [${name}]: TOKEN KO — il token remoto salvato non e' valido (status ${(authed && authed.status) || '?'}); ruota con \`nexuscrew nodes set-token ${name}\``);
+  log(`nodes test [${name}]: CREDENZIALE KO — il pairing non e' piu' valido (status ${(authed && authed.status) || '?'}); ripeti il pairing dalla PWA`);
   return { code: 1, result: 'token-ko' };
 }
 
@@ -256,11 +287,18 @@ async function defaultHttpProbe(url, headers) {
 function loadNodeOrFail(opts, log) {
   const { home, nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes up|down|restart <name>'); return null; }
+  if (!name) { log('nodes: name mancante'); return null; }
   const st = store.loadStore(nodesPath);
   const node = st ? store.getNode(st, name) : null;
   if (!node) { log(`nodes: nodo sconosciuto "${name}"`); return null; }
-  return { home, node };
+  return { home, nodesPath, store: st, node };
+}
+
+function persistAutostart(ctx, enabled) {
+  const next = store.updateNode(ctx.store, ctx.node.name, { autostart: enabled });
+  store.atomicWriteStore(ctx.nodesPath, next);
+  ctx.store = next;
+  ctx.node = store.getNode(next, ctx.node.name);
 }
 
 function nodesUp(opts) {
@@ -268,29 +306,35 @@ function nodesUp(opts) {
   const ctx = loadNodeOrFail(opts, log);
   if (!ctx) return { code: 1 };
   if (ctx.node.direction === 'inbound') return { code: 0, started: false, inbound: true };
+  if (opts.persistAutostart === true && ctx.node.autostart !== true) {
+    try { persistAutostart(ctx, true); }
+    catch (e) { log(`nodes up [${ctx.node.name}]: impossibile salvare l'avvio automatico — ${e.message}`); return { code: 1, reason: 'autostart write failed' }; }
+  }
   const r = tunnel.startForward({ home: ctx.home, node: ctx.node, localAppPort: opts.localAppPort, spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl, sshBin: opts.sshBin, logFd: opts.logFd });
   if (r.started) {
     log(`nodes up [${ctx.node.name}]: tunnel avviato (pid ${r.pid}, local ${ctx.node.localPort})`);
-    return { code: 0, started: true, pid: r.pid };
+    return { code: 0, started: true, pid: r.pid, diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
   }
   if (r.reason === 'already running') {
     log(`nodes up [${ctx.node.name}]: gia' attivo (pid ${r.pid})`);
-    return { code: 0, started: false, pid: r.pid };
+    return { code: 0, started: false, pid: r.pid, diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
   }
   // failure esplicita (ssh mancante / spawn error): surfacciata a CLI e Settings API.
   log(`nodes up [${ctx.node.name}]: avvio tunnel fallito — ${r.reason}`);
-  return { code: 1, started: false, reason: r.reason };
+  return { code: 1, started: false, reason: r.reason, diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
 }
 
 function nodesDown(opts) {
   const log = opts.log || console.log;
-  const { home, nodesPath } = resolveNodePaths(opts);
-  const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes down <name>'); return { code: 1 }; }
-  const st = store.loadStore(nodesPath);
-  if (!st || !store.getNode(st, name)) { log(`nodes down: nodo sconosciuto "${name}"`); return { code: 1 }; }
-  const r = tunnel.stopTunnel({ home, name });
-  log(`nodes down [${name}]: ${r.stopped ? `fermato (pid ${r.pid})` : r.reason}`);
+  const ctx = loadNodeOrFail(opts, log);
+  if (!ctx) return { code: 1 };
+  if (ctx.node.direction === 'inbound') return { code: 0, stopped: false, inbound: true };
+  if (opts.persistAutostart === true && ctx.node.autostart !== false) {
+    try { persistAutostart(ctx, false); }
+    catch (e) { log(`nodes down [${ctx.node.name}]: impossibile salvare lo stop — ${e.message}`); return { code: 1, reason: 'autostart write failed' }; }
+  }
+  const r = tunnel.stopTunnel({ home: ctx.home, name: ctx.node.name });
+  log(`nodes down [${ctx.node.name}]: ${r.stopped ? `fermato (pid ${r.pid})` : r.reason}`);
   return { code: 0, stopped: r.stopped };
 }
 
@@ -298,16 +342,17 @@ function nodesRestart(opts) {
   const log = opts.log || console.log;
   const ctx = loadNodeOrFail(opts, log);
   if (!ctx) return { code: 1 };
-  const args = tunnel.buildForwardArgs(ctx.node);
-  const r = tunnel.restartTunnel({ home: ctx.home, name: ctx.node.name, args, spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl, sshBin: opts.sshBin, logFd: opts.logFd });
+  if (ctx.node.direction === 'inbound') return { code: 0, started: false, inbound: true };
+  tunnel.stopTunnel({ home: ctx.home, name: ctx.node.name });
+  const r = tunnel.startForward({ home: ctx.home, node: ctx.node, localAppPort: opts.localAppPort, spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl, sshBin: opts.sshBin, logFd: opts.logFd });
   if (r.started) {
     log(`nodes restart [${ctx.node.name}]: tunnel riavviato (pid ${r.pid})`);
-    return { code: 0, started: true, pid: r.pid };
+    return { code: 0, started: true, pid: r.pid, diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
   }
   // dopo stop+start, 'already running' non e' atteso: qualunque !started e' un problema
   // esplicito (ssh mancante / spawn error), surfacciato a CLI e Settings API.
   log(`nodes restart [${ctx.node.name}]: riavvio tunnel fallito — ${r.reason || 'sconosciuto'}`);
-  return { code: 1, started: false, reason: r.reason || 'spawn failed' };
+  return { code: 1, started: false, reason: r.reason || 'spawn failed', diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
 }
 
 // --- nodes set-token (aggiorna il token remoto; MAI da argv) ----------------
@@ -316,7 +361,7 @@ function nodesSetToken(opts) {
   if (isReadonly(opts)) { log('nodes set-token: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
   const { nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes set-token <name>  (token da stdin o env NEXUSCREW_NODE_TOKEN)'); return { code: 1 }; }
+  if (!name) { log('nodes set-token: name mancante'); return { code: 1 }; }
   const st = store.loadStore(nodesPath);
   if (!st || !store.getNode(st, name)) { log(`nodes set-token: nodo sconosciuto "${name}"`); return { code: 1 }; }
   const token = readSecretToken(opts);
@@ -329,83 +374,10 @@ function nodesSetToken(opts) {
   return { code: 0, name };
 }
 
-// --- node on|off (ruolo "nodo raggiungibile", reverse tunnel) ---------------
-function nodeOn(opts) {
-  const log = opts.log || console.log;
-  if (isReadonly(opts)) { log('node on: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
-  const { home, configPath, nodesPath } = resolveNodePaths(opts);
-
-  // Gate permitlisten (§7 advisory a): il ruolo node richiede reverse tunnel con
-  // permitlisten sul rendezvous (OpenSSH >=7.8). Se la versione e' nota ed e'
-  // troppo vecchia -> rifiuta PRIMA di abilitare. Ignota -> warn, non blocca.
-  const v = (opts.sshVersion || tunnel.readSshVersion)(opts.spawnSyncImpl);
-  const supp = tunnel.sshSupportsPermitlisten(v);
-  if (supp === false) {
-    log(`node on: OpenSSH ${v.major}.${v.minor} < 7.8 — permitlisten non supportato dal client; il ruolo node NON e' abilitabile con questa toolchain`);
-    return { code: 1, reason: 'permitlisten' };
-  }
-  if (supp === null) log('node on: versione OpenSSH non determinabile — verifica che il rendezvous supporti permitlisten (>=7.8)');
-
-  // Configurazione rendezvous opzionale (flags) o gia' presente in nodes.json.
-  let st;
-  try { st = store.loadOrInitStore(nodesPath); }
-  catch (e) { log(`node on: ${e.message}`); return { code: 1 }; }
-
-  if (opts.rendezvousSsh) {
-    const localPort = loadPort(opts); // porta nexus locale da esporre
-    const publishedPort = opts.publishedPort ? Number(opts.publishedPort) : localPort;
-    const keyPath = opts.key || path.join(home, '.nexuscrew', 'keys', 'rendezvous_ed25519');
-    let pub;
-    try { pub = ensureKey(keyPath, 'rendezvous', opts); }
-    catch (e) { log(`node on: generazione chiave rendezvous fallita (${e.message})`); return { code: 1 }; }
-    let next;
-    try { next = store.setRendezvous(st, { ssh: opts.rendezvousSsh, publishedPort, localPort, keyPath }); }
-    catch (e) { log(`node on: ${e.message}`); return { code: 1 }; }
-    store.atomicWriteStore(nodesPath, next);
-    st = next;
-    log(`node on: rendezvous configurato (${opts.rendezvousSsh}, published ${publishedPort} <- local ${localPort})`);
-    log('Incolla nel ~/.ssh/authorized_keys del RENDEZVOUS (lato reverse, chiave dedicata):');
-    // permitlisten vincola i -R alla SOLA porta pubblicata (loopback esplicito).
-    log(`restrict,port-forwarding,permitlisten="127.0.0.1:${publishedPort}",command="/bin/false" ${pub}`);
-  } else if (!st.rendezvous) {
-    log('node on: nessun rendezvous configurato — passa --rendezvous user@host [--published-port N] [--key path]');
-    return { code: 1, reason: 'no rendezvous' };
-  }
-
-  // Avvia un supervisor detached per il reverse tunnel. Il supervisor ritenta
-  // con backoff: al primo setup può partire prima che la pubkey sia stata
-  // incollata sul rendezvous e convergerà automaticamente appena autorizzata.
-  const tr = tunnel.startReverse({
-    home, rendezvous: st.rendezvous,
-    spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl,
-    sshBin: opts.sshBin, logFd: opts.logFd,
-  });
-  if (!tr.started && tr.reason !== 'already running') {
-    log(`node on: reverse tunnel non avviato — ${tr.reason || 'errore sconosciuto'}; ruolo NON abilitato`);
-    return { code: 1, reason: 'reverse tunnel failed' };
-  }
-
-  const roles = writeConfigRole(configPath, 'node', true);
-  log(`node on: ruolo node ABILITATO (roles: client=${roles.client} node=${roles.node}, reverse pid=${tr.pid})`);
-  return { code: 0, roles, tunnel: { started: !!tr.started, pid: tr.pid } };
-}
-
-function nodeOff(opts) {
-  const log = opts.log || console.log;
-  if (isReadonly(opts)) { log('node off: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
-  const { home, configPath } = resolveNodePaths(opts);
-  const roles = writeConfigRole(configPath, 'node', false);
-  // Ferma un eventuale reverse tunnel attivo (best-effort, non tocca la config rendezvous).
-  try { tunnel.stopTunnel({ home, name: tunnel.REVERSE_NAME }); } catch (_) {}
-  log(`node off: ruolo node DISABILITATO (roles: client=${roles.client} node=${roles.node})`);
-  return { code: 0, roles };
-}
-
 module.exports = {
   nodesAdd, nodesList, nodesRemove, nodesTest,
   nodesUp, nodesDown, nodesRestart, nodesSetToken,
-  nodeOn, nodeOff,
   // helper esposti per test/riuso
-  assignLocalPort, defaultKeyPath, ensureKey, writeConfigRole, readSecretToken,
+  assignLocalPort, bindLocalPort, reserveLocalPort, defaultKeyPath, ensureKey, readSecretToken,
   resolveNodePaths, defaultHttpProbe,
 };

package/lib/nodes/health.js

@@ -30,23 +30,29 @@ function clearHealthCache() { cache.clear(); }
 // onesto). outbound down/401 -> 'down'/'degraded'.
 function tunnelFromHealth(h) {
   if (!h) return { status: 'unknown', managed: false };
-  if (h.status === 'passive') return { status: 'passive', managed: false };
-  if (h.transport === 'up' && h.auth === 'ok') return { status: 'up', managed: h.managed !== false };
-  if (h.transport === 'up' && h.auth === 'failed') return { status: 'degraded', managed: h.managed !== false };
-  if (h.transport === 'up') return { status: 'degraded', managed: h.managed !== false };
-  if (h.transport === 'down') return { status: 'down', managed: h.managed !== false };
+  const used = h.transportEngine ? { transport: h.transportEngine } : {};
+  if (h.status === 'passive') return { status: 'passive', managed: false, ...used };
+  if (h.transport === 'up' && h.auth === 'ok') return { status: 'up', managed: h.managed !== false, ...used };
+  if (h.transport === 'up' && h.auth === 'failed') return { status: 'degraded', managed: h.managed !== false, ...used };
+  if (h.transport === 'up') return { status: 'degraded', managed: h.managed !== false, ...used };
+  if (h.transport === 'down') return { status: 'down', managed: h.managed !== false, ...used };
   return { status: 'unknown', managed: false }; // inbound / unknown
 }
 
 async function nodeHealth({ node, home, fetchImpl, now = Date.now(), force = false }) {
   if (!node || typeof node !== 'object') return null;
-  const cacheKey = `${home || ''}\0${node.direction || 'outbound'}\0${node.name}\0${node.localPort}\0${node.nodeId || ''}\0${node.rolesKnown === true}\0${node.roles?.node === true}`;
+  const cacheKey = `${home || ''}\0${node.direction || 'outbound'}\0${node.name}\0${node.localPort}\0${node.nodeId || ''}\0${node.shared === true}\0${node.rolesKnown === true}\0${node.roles?.node === true}`;
   const cached = !force && cache.get(cacheKey);
   if (cached && (now - cached.at) < TTL_MS) return cached.health;
 
   let health;
   if (node.direction === 'inbound') {
-    if (!node.token) {
+    if (node.shared !== true) {
+      health = {
+        transport: 'unknown', auth: 'unknown', reachability: 'unknown', status: 'passive',
+        detail: 'client privato collegato (Share disattivato)', expected: true, managed: false, at: now,
+      };
+    } else if (!node.token) {
       health = {
         transport: 'unknown', auth: 'unknown', reachability: 'unknown', status: 'degraded',
         detail: 'peer inbound senza credenziale federation — re-pair', managed: false, at: now,
@@ -70,22 +76,24 @@ async function nodeHealth({ node, home, fetchImpl, now = Date.now(), force = fal
   } else {
     const ts = nodesTunnel.readTunnelState(home, node.name);
     if (ts.status !== 'up') {
-    health = {
-      transport: 'down', auth: 'unknown', reachability: 'unknown', status: 'down',
-      detail: ts.reason ? `tunnel down (${ts.reason})` : 'tunnel down',
-      managed: ts.managed !== false, at: now,
-    };
+      const diagnostic = nodesTunnel.diagnoseTunnel(home, node, ts);
+      health = {
+        transport: 'down', auth: 'unknown', reachability: 'unknown', status: 'down',
+        detail: diagnostic.detail, code: diagnostic.code, stage: diagnostic.stage,
+        ...(diagnostic.hint ? { hint: diagnostic.hint } : {}),
+        transportEngine: ts.transport || 'ssh', managed: ts.managed !== false, at: now,
+      };
     } else if (!node.token) {
     health = {
       transport: 'up', auth: 'unknown', reachability: 'unknown', status: 'degraded',
       detail: 'tunnel up, credenziali federation assenti (token mancante) — re-pair',
-      managed: true, at: now,
+      transportEngine: ts.transport || 'ssh', managed: true, at: now,
     };
     } else {
       const probed = await probeHealth({
         port: node.localPort, token: node.token, expectedInstanceId: node.nodeId || null, fetchImpl, now,
       });
-      health = { ...probed, managed: true };
+      health = { ...probed, transportEngine: ts.transport || 'ssh', managed: true };
     }
   }
   cache.set(cacheKey, { health, at: now });