@mmmbuto/nexuscrew 0.8.15 → 0.8.17

package/lib/mcp/tools.js

@@ -0,0 +1,300 @@
+'use strict';
+// Registro TOOLS del server MCP (`lib/mcp/server.js`) + helper di validazione
+// input/sessione fail-closed.
+//
+// Ogni tool e' prefissato `nc_` (anti-collisione) ed espone name/description/
+// inputSchema/annotations (readOnlyHint sui tool read-only) + handler async.
+// Gli handler ricevono `ctx` (session/api/home/fileExists/messageId) costruito
+// dal server: qui NESSUN transport diretto, solo validazione bounded degli
+// argomenti e orchestrazione delle chiamate via ctx.api. Ordine, nomi, schemi,
+// handler, identity gate e semantica read/write sono preservati EXACT.
+const path = require('node:path');
+const {
+  NODE_ID_RE, orderedDeckMembers, fleetStatusPath, fleetCellsBySession,
+  routePath, topologyOwners, memberOwnerId, parseCellTarget, readCellDirectory,
+} = require('./cells.js');
+
+// --- helper input tool (fail-closed) ------------------------------------------
+function argString(args, key, { required = false, max = 4096 } = {}) {
+  const v = args[key];
+  if (v === undefined || v === null) {
+    if (required) throw new Error(`parametro "${key}" obbligatorio`);
+    return undefined;
+  }
+  if (typeof v !== 'string') throw new Error(`parametro "${key}" deve essere una stringa`);
+  if (required && !v.trim()) throw new Error(`parametro "${key}" non puo' essere vuoto`);
+  if (v.length > max) throw new Error(`parametro "${key}" troppo lungo (max ${max})`);
+  return v;
+}
+
+function requireSession(session, tool) {
+  if (session) return session;
+  throw new Error(
+    `${tool}: sessione tmux non identificata — serve $TMUX (dentro tmux) o NEXUSCREW_MCP_SESSION`,
+  );
+}
+
+// --- definizione tool (prefisso nc_ anti-collisione) ---------------------------
+// annotations.readOnlyHint:true sui tool che non mutano nulla (§1).
+const TOOLS = [
+  {
+    name: 'nc_notify',
+    description: 'Invia una notifica all\'operatore via NexusCrew (UI aperte + web push). Usala per esiti, avvisi e richieste di attenzione non bloccanti.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'titolo breve della notifica' },
+        body: { type: 'string', description: 'dettaglio opzionale' },
+        urgency: { type: 'string', enum: ['normal', 'high'], description: 'default normal' },
+      },
+      required: ['title'],
+    },
+    async handler(args, ctx) {
+      const title = argString(args, 'title', { required: true, max: 200 });
+      const body = argString(args, 'body', { max: 2000 });
+      const urgency = argString(args, 'urgency', { max: 16 });
+      if (urgency !== undefined && urgency !== 'normal' && urgency !== 'high') {
+        throw new Error('urgency deve essere "normal" o "high"');
+      }
+      const session = await ctx.session();
+      const payload = { title, ...(body ? { body } : {}), ...(urgency ? { urgency } : {}) };
+      if (session) payload.session = session;
+      const j = await ctx.api('POST', '/api/notify', payload);
+      return { delivered: j.delivered };
+    },
+  },
+  {
+    name: 'nc_ask',
+    description: 'Pone una domanda all\'operatore e ritorna SUBITO (non bloccare in attesa): la risposta arrivera\' come messaggio incollato in questa sessione tmux, prefissato [human reply · ask#<id>] per default.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        question: { type: 'string', description: 'la domanda per l\'operatore' },
+        options: { type: 'array', items: { type: 'string' }, description: 'opzioni di risposta rapida (max 8)' },
+      },
+      required: ['question'],
+    },
+    async handler(args, ctx) {
+      const question = argString(args, 'question', { required: true, max: 2000 });
+      if (args.options !== undefined && !Array.isArray(args.options)) {
+        throw new Error('options deve essere un array di stringhe');
+      }
+      const session = requireSession(await ctx.session(), 'nc_ask');
+      const j = await ctx.api('POST', '/api/asks', {
+        question, ...(args.options ? { options: args.options } : {}), session,
+      });
+      return {
+        askId: j.id,
+        note: 'la risposta dell\'operatore arrivera\' come messaggio incollato in questa sessione tmux',
+      };
+    },
+  },
+  {
+    name: 'nc_send_file',
+    description: 'Consegna un file all\'operatore: lo copia nell\'outbox NexusCrew di questa sessione (badge + notifica automatici). Path assoluto sotto HOME.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'path assoluto del file (sotto HOME)' },
+        caption: { type: 'string', description: 'didascalia opzionale' },
+      },
+      required: ['path'],
+    },
+    async handler(args, ctx) {
+      const p = argString(args, 'path', { required: true, max: 4096 });
+      const caption = argString(args, 'caption', { max: 500 });
+      if (!path.isAbsolute(p)) throw new Error('path deve essere assoluto');
+      // Pre-check locale (errore immediato e chiaro); la validazione autoritativa
+      // (realpath sotto HOME, file regolare) la rifa' comunque il server.
+      if (!ctx.fileExists(p)) throw new Error(`file inesistente: ${p}`);
+      const home = ctx.home();
+      if (p !== home && !p.startsWith(home + path.sep)) throw new Error('path fuori da HOME');
+      const session = requireSession(await ctx.session(), 'nc_send_file');
+      const j = await ctx.api('POST', '/api/files/outbox', {
+        session, path: p, ...(caption ? { caption } : {}),
+      });
+      return { name: j.name, box: 'outbox' };
+    },
+  },
+  {
+    name: 'nc_status',
+    description: 'Stato read-only di NexusCrew: sessioni tmux vive e celle della flotta (se abilitata).',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { readOnlyHint: true },
+    async handler(_args, ctx) {
+      const s = await ctx.api('GET', '/api/sessions');
+      const sessions = (Array.isArray(s.sessions) ? s.sessions : [])
+        .map((x) => ({ name: x.name, active: !!x.attached }));
+      let fleet = null;
+      try {
+        const f = await ctx.api('GET', '/api/fleet/status');
+        if (f && f.available) {
+          fleet = {
+            cells: (Array.isArray(f.cells) ? f.cells : []).map((c) => ({
+              cell: c.cell, session: c.tmuxSession, engine: c.engine, active: !!c.active,
+            })),
+          };
+        }
+      } catch (_) { /* fleet opzionale: assente/disabilitata -> null */ }
+      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_cells',
+    description: 'Directory read-only di tutte le celle Fleet autorizzate nella rete NexusCrew. Usa l\'id owner-qualified restituito per evitare nomi ambigui.',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { readOnlyHint: true },
+    async handler(_args, ctx) {
+      const callerSession = await ctx.session();
+      return readCellDirectory(ctx, callerSession);
+    },
+  },
+  {
+    name: 'nc_send_cell',
+    description: 'Invia e sottopone un messaggio a una cella Fleet attiva autorizzata. target deve essere l\'id esatto restituito da nc_cells; submitted non significa lavoro completato.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'id owner-qualified restituito da nc_cells: <instanceId>:<cell>' },
+        message: { type: 'string', description: 'messaggio o task da sottoporre (max 8000 caratteri)' },
+      },
+      required: ['target', 'message'],
+    },
+    async handler(args, ctx) {
+      const targetRef = parseCellTarget(argString(args, 'target', { required: true, max: 128 }));
+      if (!targetRef) throw new Error('target non valido: usa l\'id esatto restituito da nc_cells');
+      const message = argString(args, 'message', { required: true, max: 8000 });
+      for (let i = 0; i < message.length; i += 1) {
+        const code = message.charCodeAt(i);
+        if (code === 9 || code === 10 || code === 13) continue;
+        if (code < 32 || code === 127) throw new Error('message contiene caratteri di controllo non ammessi');
+      }
+      const callerSession = requireSession(await ctx.session(), 'nc_send_cell');
+      const directory = await readCellDirectory(ctx, callerSession);
+      const sender = directory.cells.find((cell) => cell.self && cell.active);
+      if (!sender) throw new Error('nc_send_cell: la sessione chiamante non e\' una cella Fleet attiva locale');
+      const target = directory.cells.find((cell) => cell.instanceId === targetRef.instanceId
+        && cell.cell === targetRef.cell);
+      if (!target) throw new Error('cella destinataria non trovata nella rete autorizzata');
+      if (!target.canReceive) throw new Error('cella destinataria non attiva; nessun messaggio accodato');
+      const apiPath = target.route === 'local'
+        ? '/api/cells/send' : routePath(target.route.split('/'), 'cells/send');
+      if (!apiPath) throw new Error('route destinataria non valida');
+      const id = ctx.messageId();
+      const receipt = await ctx.api('POST', apiPath, {
+        id,
+        from: { instanceId: sender.instanceId, cell: sender.cell, tmuxSession: sender.tmuxSession },
+        to: { instanceId: target.instanceId, cell: target.cell, tmuxSession: target.tmuxSession },
+        message,
+      });
+      return {
+        id: receipt.id,
+        status: receipt.status,
+        at: receipt.at,
+        to: receipt.to,
+        note: receipt.note || 'submitted conferma il trasporto, non il completamento del task',
+      };
+    },
+  },
+  {
+    name: 'nc_inbox',
+    description: 'Elenca i file ricevuti nell\'inbox NexusCrew di questa sessione (read-only).',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { readOnlyHint: true },
+    async handler(_args, ctx) {
+      const session = requireSession(await ctx.session(), 'nc_inbox');
+      const j = await ctx.api('GET', `/api/files?session=${encodeURIComponent(session)}`);
+      return { inbox: Array.isArray(j.inbox) ? j.inbox : [] };
+    },
+  },
+];
+
+module.exports = { TOOLS, argString, requireSession };

package/lib/nodes/tunnel-supervisor.js

@@ -3,6 +3,7 @@
 // Detached supervisor for one SSH tunnel. The parent NexusCrew process can exit;
 // this process keeps the tunnel alive and retries failures with bounded backoff.
 const fs = require('node:fs');
+const net = require('node:net');
 const path = require('node:path');
 const { spawn } = require('node:child_process');
 const { backoffDelay } = require('./tunnel.js');
@@ -24,13 +25,70 @@ let stopping = false;
 let attempt = 0;
 let retryTimer = null;
 let upTimer = null;
+let forwardProbeTimer = null;
+let forwardSocket = null;
 let ownershipWaitTimer = null;
 let ownershipTimer = null;
 
+function localForwardPort(args) {
+  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 port = match ? Number(match[1]) : 0;
+    if (Number.isInteger(port) && port >= 1 && port <= 65535) return port;
+  }
+  return null;
+}
+
+const forwardPort = localForwardPort(sshArgs);
+
 function logEvent(message) {
   try { process.stderr.write(`[nexuscrew] ${String(message).replace(/[\r\n]+/g, ' ')}\n`); } catch (_) {}
 }
 
+function clearForwardProbe() {
+  clearTimeout(forwardProbeTimer);
+  forwardProbeTimer = null;
+  if (forwardSocket) {
+    try { forwardSocket.destroy(); } catch (_) {}
+    forwardSocket = null;
+  }
+}
+
+// A live ssh PID is not proof of authentication: the process may still be
+// 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.
+function probeForward(expectedChild) {
+  if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
+  if (!forwardPort) {
+    writeState('transport-probing', { sshPid: child.pid, detail: 'local forward unavailable' });
+    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;
+    if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
+    if (ready) {
+      attempt = 0;
+      logEvent(`forward ready stableMs=${stableMs}`);
+      if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'tcp-forward' })) stop();
+      return;
+    }
+    if (!writeState('transport-probing', { sshPid: child.pid, stableMs })) 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));
+}
+
 function ownsGeneration() {
   try {
     const meta = JSON.parse(fs.readFileSync(pidPath, 'utf8'));
@@ -79,19 +137,18 @@ function run() {
     if (failureHandled) return;
     failureHandled = true;
     clearTimeout(upTimer);
+    clearForwardProbe();
     child = null;
     scheduleRetry(detail);
   };
   child.once('spawn', () => {
     logEvent(`ssh attempt=${attempt + 1} spawned`);
-    // 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.
+    // 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) {
-        attempt = 0;
-        logEvent(`transport ready stableMs=${stableMs}`);
-        if (!writeState('transport-ready', { sshPid: child.pid, stableMs })) stop();
+        probeForward(child);
       }
     }, stableMs);
   });
@@ -109,6 +166,7 @@ function run() {
 function finish() {
   clearTimeout(retryTimer);
   clearTimeout(upTimer);
+  clearForwardProbe();
   clearTimeout(ownershipWaitTimer);
   clearInterval(ownershipTimer);
   if (ownsGeneration()) {
@@ -126,6 +184,7 @@ function stop() {
   stopping = true;
   clearTimeout(retryTimer);
   clearTimeout(upTimer);
+  clearForwardProbe();
   if (child && child.exitCode == null) {
     try { child.kill('SIGTERM'); } catch (_) {}
     setTimeout(() => { try { if (child && child.exitCode == null) child.kill('SIGKILL'); } catch (_) {} finish(); }, 1500).unref();

package/lib/nodes/tunnel.js

@@ -28,6 +28,7 @@ const SSH_BASE_OPTS = Object.freeze([
   '-o', 'ServerAliveInterval=30',
   '-o', 'ServerAliveCountMax=3',
   '-o', 'BatchMode=yes',
+  '-o', 'ConnectTimeout=15',
   // A Host stanza may set LogLevel=QUIET, leaving the per-tunnel diagnostic
   // completely empty even for bind/auth/forward failures.  ERROR is still
   // quiet on success and never logs key material, but preserves real failures.
@@ -101,6 +102,49 @@ function tunnelLogPath(home, name) {
   return path.join(tunnelDir(home), `${name}.log`);
 }
 
+// Cleanup identifier for pre-0.8.10 standalone rendezvous supervisors. New
+// runtimes never start this second connection; reconciliation can still stop a
+// stale legacy process left by an older install.
+const REVERSE_NAME = '__rendezvous__';
+
+// Reconcile detached supervisors against the authoritative node store. A
+// server crash or an older rollback could leave a valid supervisor pidfile
+// after its node disappeared; startup and `nexuscrew stop` must recover it
+// without broad process matching. Only strict NexusCrew pidfile names are
+// considered and stopTunnel still performs pid+cmd verification.
+function tunnelPidNames(home) {
+  const dir = tunnelDir(home);
+  try {
+    const root = fs.lstatSync(dir);
+    if (root.isSymbolicLink() || !root.isDirectory()) return [];
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && !entry.isSymbolicLink() && entry.name.endsWith('.pid'))
+      .map((entry) => entry.name.slice(0, -4))
+      .filter((name) => store.NODE_NAME_RE.test(name) || name === REVERSE_NAME)
+      .sort();
+  } catch (_) { return []; }
+}
+
+function reconcileTunnelSupervisors({ home = os.homedir(), configuredNames = [], stopImpl } = {}) {
+  const keep = new Set((Array.isArray(configuredNames) ? configuredNames : [])
+    .filter((name) => store.NODE_NAME_RE.test(String(name || ''))));
+  const stopOne = typeof stopImpl === 'function' ? stopImpl : stopTunnel;
+  const result = { kept: [], stopped: [], cleaned: [], failed: [] };
+  const safeAbsent = new Set(['no pidfile', 'stale (pid dead)', 'pid reuse (cmd mismatch)']);
+  for (const name of tunnelPidNames(home)) {
+    if (keep.has(name)) { result.kept.push(name); continue; }
+    try {
+      const out = stopOne({ home, name });
+      if (out && out.stopped) result.stopped.push(name);
+      else if (out && safeAbsent.has(out.reason)) result.cleaned.push(name);
+      else result.failed.push({ name, reason: (out && out.reason) || 'stop failed' });
+    } catch (error) {
+      result.failed.push({ name, reason: String((error && error.message) || error) });
+    }
+  }
+  return result;
+}
+
 function prepareTunnelDir(home) {
   const dir = tunnelDir(home);
   try {
@@ -150,7 +194,10 @@ function classifySshFailure(text, remotePort) {
     };
   }
   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' };
+    return {
+      code: 'ssh-auth-failed', detail: 'autenticazione SSH rifiutata',
+      hint: 'usa lo stesso Host o alias che funziona con il client SSH di questo dispositivo; chiavi e alias restano locali e 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' };
@@ -454,11 +501,6 @@ function startForward(opts) {
   return startTunnel({ ...opts, sshBin, name: node.name, args });
 }
 
-// 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__';
-
 // 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) {
@@ -476,6 +518,7 @@ module.exports = {
   buildForwardArgs, backoffDelay,
   tunnelDir, tunnelPidPath, tunnelLogPath, tunnelStatePath, readTunnelState,
   prepareTunnelDir, openTunnelLog,
+  tunnelPidNames, reconcileTunnelSupervisors,
   classifySshFailure, readTunnelDiagnostic,
   diagnoseTunnel,
   removeStateIfOwned, supervisorExited,

package/lib/runtime/env.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const os = require('node:os');
+const path = require('node:path');
 
 const MINIMAL_ENV_KEYS = Object.freeze([
   'PATH', 'HOME', 'SHELL', 'TERM', 'COLORTERM', 'LANG', 'LANGUAGE',
@@ -37,6 +38,33 @@ function withUtf8Locale(source = process.env, { platform = process.platform } =
   return env;
 }
 
+// Termux installs tmux with TMUX_TMPDIR=$PREFIX/var/run via a profile.d
+// snippet. Background runtimes and Termux:Boot do not necessarily source that
+// profile, so a first `tmux new-session` would otherwise try the Android/FHS
+// fallback instead of the canonical Termux socket directory. Derive only from
+// an explicit PREFIX or the standard .../files/home layout; never guess paths
+// for Linux/macOS.
+function termuxRuntimePaths(source = process.env, opts = {}) {
+  const platform = opts.platform || process.platform;
+  const home = String(source.HOME || opts.home || os.homedir());
+  const suppliedPrefix = String(source.PREFIX || '');
+  const termux = platform === 'android'
+    || suppliedPrefix.includes('com.termux')
+    || (path.basename(home) === 'home' && path.basename(path.dirname(home)) === 'files');
+  if (!termux) return null;
+
+  let prefix = suppliedPrefix;
+  if (!prefix && path.basename(home) === 'home' && path.basename(path.dirname(home)) === 'files') {
+    prefix = path.join(path.dirname(home), 'usr');
+  }
+  if (!path.isAbsolute(prefix)) return null;
+  return {
+    prefix,
+    tmpdir: String(source.TMPDIR || path.join(prefix, 'tmp')),
+    tmuxTmpdir: String(source.TMUX_TMPDIR || path.join(prefix, 'var', 'run')),
+  };
+}
+
 function minimalRuntimeEnv(source = process.env, opts = {}) {
   const selected = {};
   for (const key of MINIMAL_ENV_KEYS) {
@@ -44,7 +72,16 @@ function minimalRuntimeEnv(source = process.env, opts = {}) {
   }
   if (!selected.PATH) selected.PATH = '/usr/local/bin:/usr/bin:/bin';
   if (!selected.HOME) selected.HOME = opts.home || os.homedir();
+  const termux = termuxRuntimePaths(selected, opts);
+  if (termux) {
+    if (!selected.PREFIX) selected.PREFIX = termux.prefix;
+    if (!selected.TMPDIR) selected.TMPDIR = termux.tmpdir;
+    if (!selected.TMUX_TMPDIR) selected.TMUX_TMPDIR = termux.tmuxTmpdir;
+  }
   return withUtf8Locale(selected, opts);
 }
 
-module.exports = { MINIMAL_ENV_KEYS, UTF8_RE, localeDefaults, withUtf8Locale, minimalRuntimeEnv };
+module.exports = {
+  MINIMAL_ENV_KEYS, UTF8_RE, localeDefaults, withUtf8Locale,
+  termuxRuntimePaths, minimalRuntimeEnv,
+};

package/lib/server.js

@@ -136,6 +136,14 @@ function createServer(opts = {}) {
     if (tunnelsStarted) return;
     tunnelsStarted = true;
     const st = nodesStore.loadStore(nodesPath);
+    const configured = ((st && st.nodes) || [])
+      .filter((node) => node.direction !== 'inbound')
+      .map((node) => node.name);
+    const reconcile = cfg.reconcileTunnelSupervisorsImpl || nodesTunnel.reconcileTunnelSupervisors;
+    const recovered = reconcile({ home: cfg.home || os.homedir(), configuredNames: configured });
+    for (const failure of recovered.failed || []) {
+      process.stderr.write(`[nexuscrew] orphan tunnel cleanup failed for ${failure.name}: ${failure.reason}\n`);
+    }
     // Exactly one connection per configured hub. Legacy `roles.node` /
     // rendezvous data is migration-only and never starts a second hidden SSH
     // process. Publishing this device is the optional -R on its outbound link.