@mmmbuto/nexuscrew 0.8.11 → 0.8.13

package/lib/fleet/managed.js

@@ -140,24 +140,38 @@ function defaultDefinitions() {
   };
 }
 
-function parseEnvFile(file) {
+function parseAssignments(raw) {
   const out = {};
-  let raw;
-  try {
-    const st = fs.lstatSync(file);
-    if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o077)) return out;
-    raw = fs.readFileSync(file, 'utf8');
-  } catch (_) { return out; }
   for (const line of raw.split(/\r?\n/)) {
     const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
     if (!m) continue;
     let v = m[2];
     if ((v.startsWith("'") && v.endsWith("'")) || (v.startsWith('"') && v.endsWith('"'))) v = v.slice(1, -1);
+    // This is a data parser, not a shell. Reject syntax that would have a
+    // different meaning if sourced instead of treating it as a credential.
+    if (/\$\(|`|\x00|\r|\n/.test(v)) continue;
     out[m[1]] = v;
   }
   return out;
 }
 
+function parseEnvFile(file) {
+  try {
+    const st = fs.lstatSync(file);
+    if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o077) || st.size > 256 * 1024) return {};
+    return parseAssignments(fs.readFileSync(file, 'utf8'));
+  } catch (_) { return {}; }
+}
+
+function parseProviderShellFile(file) {
+  try {
+    const st = fs.lstatSync(file);
+    if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o022) || st.size > 256 * 1024) return {};
+    if (typeof process.getuid === 'function' && st.uid !== process.getuid()) return {};
+    return parseAssignments(fs.readFileSync(file, 'utf8'));
+  } catch (_) { return {}; }
+}
+
 function binaryCandidates(client, home) {
   const prefix = process.env.PREFIX || '';
   const bin = client;
@@ -180,17 +194,51 @@ function findBinary(client, home) {
   return null;
 }
 
+// Termux reports process.platform === 'android' and deliberately has no
+// /usr/bin/env.  npm CLI shims commonly resolve to a JavaScript file with
+// `#!/usr/bin/env node`; direct tmux exec then fails in the kernel before the
+// client starts.  Detect only that explicit Node shebang and invoke it through
+// the already-running trusted Node executable.  Native and shell binaries keep
+// their original direct-exec path.
+function needsExplicitNode(binary, platform = process.platform) {
+  if (platform !== 'android') return false;
+  try {
+    const fd = fs.openSync(binary, 'r');
+    try {
+      const buffer = Buffer.alloc(160);
+      const length = fs.readSync(fd, buffer, 0, buffer.length, 0);
+      const first = buffer.subarray(0, length).toString('utf8').split(/\r?\n/, 1)[0];
+      return /^#!\s*\/usr\/bin\/env(?:\s+-S)?\s+node(?:\s|$)/.test(first);
+    } finally { fs.closeSync(fd); }
+  } catch (_) { return false; }
+}
+
 function secretsPath(cfg, home) {
   return cfg.providerSecretsPath || process.env.NEXUSCREW_PROVIDER_SECRETS || path.join(home, '.nexuscrew', 'providers.env');
 }
 
+function shellProvidersPath(cfg, home) {
+  return cfg.providerShellPath || process.env.NEXUSCREW_PROVIDER_SHELL
+    || path.join(home, '.config', 'ai-shell', 'providers.zsh');
+}
+
+function credentialSources(cfg, home) {
+  return {
+    runtime: cfg.env || process.env,
+    shell: parseProviderShellFile(shellProvidersPath(cfg, home)),
+    legacy: parseEnvFile(secretsPath(cfg, home)),
+  };
+}
+
 function credential(profile, spec, cfg, home) {
   if (profile.auth === 'login' || profile.auth === 'none') return { envKey: profile.auth, value: '' };
   const envKey = profile.auth === 'dynamic' ? spec.envKey : profile.auth;
-  const runtimeEnv = cfg.env || process.env;
-  let value = runtimeEnv[envKey] || '';
-  // Preserve 0.8.0 Z.AI/Ollama Cloud behavior, but new Custom never reads disk.
-  if (!value && profile.legacySecrets) value = parseEnvFile(secretsPath(cfg, home))[envKey] || '';
+  const sources = credentialSources(cfg, home);
+  // The fixed shell file is already the user's environment source. Values are
+  // consumed only in memory and passed to the selected child; never persisted
+  // in fleet.json, service files, API responses or logs.
+  let value = sources.runtime[envKey] || sources.shell[envKey] || '';
+  if (!value && profile.legacySecrets) value = sources.legacy[envKey] || '';
   return { envKey, value };
 }
 
@@ -202,7 +250,9 @@ async function discoverOllamaModels(opts = {}) {
   if (typeof fetchImpl !== 'function') return [...OLLAMA_CLOUD_MODELS];
   try {
     const home = opts.home || require('node:os').homedir();
-    const apiKey = opts.apiKey || (opts.env || process.env).OLLAMA_API_KEY || parseEnvFile(secretsPath(opts, home)).OLLAMA_API_KEY;
+    const sources = credentialSources(opts, home);
+    const apiKey = opts.apiKey || sources.runtime.OLLAMA_API_KEY
+      || sources.shell.OLLAMA_API_KEY || sources.legacy.OLLAMA_API_KEY;
     if (!apiKey) throw new Error('OLLAMA_API_KEY missing');
     const response = await fetchImpl('https://ollama.com/api/tags', { headers: { authorization: `Bearer ${apiKey}` }, signal: AbortSignal.timeout?.(2500) });
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
@@ -393,7 +443,14 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     if (model) args.push('--model', model);
   }
   if (cell?.prompt) args.push(cell.prompt);
-  return { ok: true, info, engine: { ...engine, command: info.binary, args, env, promptMode: 'managed-argv' } };
+  let command = info.binary;
+  if (needsExplicitNode(info.binary, cfg.platform || process.platform)) {
+    command = cfg.nodeExecPath || process.execPath;
+    args.unshift(info.binary);
+  }
+  return { ok: true, info, engine: {
+    ...engine, command, args, env, promptMode: 'managed-argv', clientBinary: info.binary,
+  } };
 }
 
 function publicCatalog() {
@@ -410,6 +467,6 @@ function publicCatalog() {
 
 module.exports = {
   CATALOG, OLLAMA_CLOUD_MODELS, OLLAMA_CONTEXT, CLIENT_LABELS, normalizeManagedSpec,
-  defaultDefinitions, describeManaged, discoverOllamaModels, resolveManagedEngine,
-  discoverPiModels, parseEnvFile, findBinary, publicCatalog, writePiProviderExtension,
+  defaultDefinitions, describeManaged, discoverOllamaModels, resolveManagedEngine, needsExplicitNode,
+  discoverPiModels, parseEnvFile, parseProviderShellFile, findBinary, publicCatalog, writePiProviderExtension,
 };

package/lib/fleet/routes.js

@@ -27,7 +27,7 @@ function fleetRoutes(fleetP, cfg = {}) {
   const r = express.Router();
   const smallJson = express.json({ limit: '4kb' });
   const restoreJson = express.json({ limit: '256kb' });
-  r.use((req, res, next) => (req.path === '/restore-cells' ? restoreJson : smallJson)(req, res, next));
+  r.use((req, res, next) => (req.path === '/restore-cells' || req.path === '/restore-engines' ? restoreJson : smallJson)(req, res, next));
 
   const readonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
 
@@ -113,6 +113,11 @@ function fleetRoutes(fleetP, cfg = {}) {
   r.post('/edit-cell', guard((f, b) => { requireCap(f, 'edit'); return f.editCell(b.id, b.patch); }, { mutate: true }));
   r.post('/remove-cell', guard((f, b) => { requireCap(f, 'remove'); return f.removeCell(b.id, { stop: b.stop === true }); }, { mutate: true }));
   r.post('/restore-cells', guard((f, b) => { requireCap(f, 'restore'); return f.restoreCells(b.cells); }, { mutate: true }));
+  r.post('/restore-engines', guard((f, b) => {
+    requireCap(f, 'restore');
+    if (typeof f.restoreEngines !== 'function') { const e = new Error('not supported by this fleet provider'); e.status = 501; throw e; }
+    return f.restoreEngines(b.engines, { overwrite: b.overwrite === true });
+  }, { mutate: true }));
   // Riconciliazione sessione tmux esistente (cella Fleet legacy orfana) in cella
   // gestita fleet.json. Capability 'define' (solo builtin): external legacy -> 501.
   r.post('/import-cell', guard(async (f, b) => { requireCap(f, 'import'); return f.importCell(b || {}); }, { mutate: true }));

package/lib/mcp/server.js

@@ -3,14 +3,16 @@
 //
 // Porta NexusCrew DENTRO le sessioni AI (Claude Code / codex-vl) come server
 // MCP: notifiche umane, richieste di attenzione (ask), consegna file, stato
-// read-only. Il bus cella↔cella resta a crewd/crew: questo bridge parla SOLO
-// con l'HTTP API locale di NexusCrew (loopback + Bearer).
+// read-only e directory/invio autenticato tra celle Fleet attive. Il bridge
+// parla SOLO con l'HTTP API locale di NexusCrew (loopback + Bearer); le route
+// federate applicano ACL e identita' owner-qualified lato server.
 //
 // Protocollo: JSON-RPC 2.0, UN messaggio JSON per riga (stdio framing MCP).
 // Hand-rolled minimale, zero dipendenze SDK (stile del repo). Fail-closed:
 // garbage in input non crasha MAI il processo — risponde un errore JSON-RPC.
 // Niente log su stdout (corromperebbe il canale): diagnostica su stderr.
 const readline = require('node:readline');
+const crypto = require('node:crypto');
 const os = require('node:os');
 const path = require('node:path');
 const { execFile } = require('node:child_process');
@@ -95,6 +97,7 @@ function orderedDeckMembers(deck) {
 
 const NODE_PART_RE = /^[a-z0-9-]{1,32}$/;
 const NODE_ID_RE = /^[a-f0-9]{16,64}$/;
+const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
 function fleetStatusPath(node) {
   if (!node) return '/api/fleet/status';
   const parts = String(node).split('/');
@@ -144,6 +147,69 @@ function memberOwnerId(member, deckOwner, ownerTopology) {
   return found ? found.instanceId : null;
 }
 
+function parseCellTarget(value) {
+  if (typeof value !== 'string') return null;
+  const split = value.indexOf(':');
+  if (split < 16) return null;
+  const instanceId = value.slice(0, split);
+  const cell = value.slice(split + 1);
+  return NODE_ID_RE.test(instanceId) && CELL_ID_RE.test(cell) ? { instanceId, cell } : null;
+}
+
+function normalizeCellPayload(payload, owner, callerSession = null) {
+  if (!payload || payload.instanceId !== owner.instanceId || !Array.isArray(payload.cells)) return [];
+  const route = owner.route.length ? owner.route.join('/') : 'local';
+  const seen = new Set();
+  const out = [];
+  for (const raw of payload.cells) {
+    if (!raw || raw.instanceId !== owner.instanceId || !CELL_ID_RE.test(String(raw.cell || ''))
+      || typeof raw.tmuxSession !== 'string' || !isValidSession(raw.tmuxSession)
+      || seen.has(raw.cell)) continue;
+    seen.add(raw.cell);
+    out.push({
+      id: `${owner.instanceId}:${raw.cell}`,
+      instanceId: owner.instanceId,
+      owner: owner.label,
+      route,
+      cell: raw.cell,
+      tmuxSession: raw.tmuxSession,
+      engine: typeof raw.engine === 'string' ? raw.engine : '',
+      model: typeof raw.model === 'string' ? raw.model : '',
+      active: raw.active === true,
+      canReceive: raw.canReceive === true,
+      lastSeen: Number.isFinite(raw.lastSeen) ? raw.lastSeen : null,
+      self: owner.route.length === 0 && callerSession === raw.tmuxSession,
+    });
+  }
+  return out;
+}
+
+async function readCellDirectory(ctx, callerSession = null) {
+  const [config, topology] = await Promise.all([
+    ctx.api('GET', '/api/config'), ctx.api('GET', '/api/topology'),
+  ]);
+  const localId = String(config && config.instanceId || '');
+  if (!NODE_ID_RE.test(localId)) throw new Error('instanceId locale non disponibile');
+  const owners = [{ instanceId: localId, route: [], label: 'Local', stale: false },
+    ...topologyOwners(topology).filter((owner) => !owner.stale && owner.instanceId !== localId)];
+  const cells = [];
+  const unavailable = [];
+  await Promise.all(owners.map(async (owner) => {
+    const apiPath = owner.route.length ? routePath(owner.route, 'cells') : '/api/cells';
+    if (!apiPath) return;
+    try {
+      cells.push(...normalizeCellPayload(await ctx.api('GET', apiPath), owner, callerSession));
+    } catch (_) {
+      unavailable.push({ instanceId: owner.instanceId, owner: owner.label,
+        route: owner.route.length ? owner.route.join('/') : 'local' });
+    }
+  }));
+  cells.sort((a, b) => (a.route === 'local' ? -1 : b.route === 'local' ? 1
+    : a.route.localeCompare(b.route)) || a.cell.localeCompare(b.cell));
+  unavailable.sort((a, b) => a.route.localeCompare(b.route));
+  return { nodeId: localId, cells, unavailable };
+}
+
 // --- definizione tool (prefisso nc_ anti-collisione) ---------------------------
 // annotations.readOnlyHint:true sui tool che non mutano nulla (§1).
 const TOOLS = [
@@ -337,6 +403,63 @@ const TOOLS = [
       };
     },
   },
+  {
+    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).',
@@ -357,6 +480,7 @@ function createMcpServer(opts = {}) {
   const env = opts.env || process.env;
   const execFileImpl = opts.execFileImpl || execFile;
   const fetchImpl = opts.fetchImpl || fetch;
+  const idFactory = opts.idFactory || (() => crypto.randomUUID());
   const errlog = opts.errlog || ((s) => { try { process.stderr.write(`${s}\n`); } catch (_) {} });
   // Config UNICA fonte per porta/token path: stessa risoluzione del server
   // (config.json + env NEXUSCREW_CONFIG_FILE/PORT/TOKEN_FILE). opts.config per test.
@@ -405,6 +529,7 @@ function createMcpServer(opts = {}) {
     api,
     home: () => env.HOME || os.homedir(),
     fileExists: (p) => { try { return require('node:fs').statSync(p).isFile(); } catch (_) { return false; } },
+    messageId: () => String(idFactory()).toLowerCase(),
   };
 
   function write(msg) {
@@ -539,4 +664,7 @@ function startMcp(opts = {}) {
   return srv;
 }
 
-module.exports = { createMcpServer, startMcp, resolveSession, TOOLS };
+module.exports = {
+  createMcpServer, startMcp, resolveSession, TOOLS,
+  parseCellTarget, normalizeCellPayload, readCellDirectory,
+};

package/lib/nodes/tunnel-supervisor.js

@@ -14,6 +14,9 @@ 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;
+const ownershipGraceRaw = Number(process.env.NEXUSCREW_TUNNEL_OWNERSHIP_GRACE_MS || 2000);
+const ownershipGraceMs = Number.isFinite(ownershipGraceRaw) && ownershipGraceRaw >= 100
+  ? Math.min(ownershipGraceRaw, 10000) : 2000;
 if (!sshBin || !statePath || !pidPath || !runId) process.exit(2);
 
 let child = null;
@@ -21,6 +24,8 @@ let stopping = false;
 let attempt = 0;
 let retryTimer = null;
 let upTimer = null;
+let ownershipWaitTimer = null;
+let ownershipTimer = null;
 
 function ownsGeneration() {
   try {
@@ -48,14 +53,14 @@ function writeState(status, extra = {}) {
 function scheduleRetry(detail) {
   if (stopping) return finish();
   const delayMs = backoffDelay(attempt, { baseMs: 1000, capMs: 60000 });
-  writeState('retrying', { delayMs, detail });
+  if (!writeState('retrying', { delayMs, detail })) return stop();
   attempt += 1;
   retryTimer = setTimeout(run, delayMs);
 }
 
 function run() {
   if (stopping) return finish();
-  writeState('starting');
+  if (!writeState('starting')) return stop();
   try {
     child = spawn(sshBin, sshArgs, { stdio: 'inherit' });
   } catch (e) {
@@ -78,7 +83,7 @@ function run() {
     upTimer = setTimeout(() => {
       if (!stopping && child && child.exitCode == null) {
         attempt = 0;
-        writeState('transport-ready', { sshPid: child.pid, stableMs });
+        if (!writeState('transport-ready', { sshPid: child.pid, stableMs })) stop();
       }
     }, stableMs);
   });
@@ -94,6 +99,8 @@ function run() {
 function finish() {
   clearTimeout(retryTimer);
   clearTimeout(upTimer);
+  clearTimeout(ownershipWaitTimer);
+  clearInterval(ownershipTimer);
   if (ownsGeneration()) {
     writeState('down');
     try {
@@ -119,4 +126,19 @@ function stop() {
 
 process.on('SIGTERM', stop);
 process.on('SIGINT', stop);
-run();
+
+// The parent can only write our PID after spawn returns. Give that narrow race
+// a bounded grace window, then enforce generation ownership continuously. A
+// replaced/removed pidfile must stop both supervisor and ssh instead of leaving
+// an invisible retrying orphan behind.
+const ownershipDeadline = Date.now() + ownershipGraceMs;
+function acquireGeneration() {
+  if (stopping) return finish();
+  if (ownsGeneration()) {
+    ownershipTimer = setInterval(() => { if (!ownsGeneration()) stop(); }, 500);
+    return run();
+  }
+  if (Date.now() >= ownershipDeadline) return finish();
+  ownershipWaitTimer = setTimeout(acquireGeneration, 20);
+}
+acquireGeneration();

package/lib/nodes/tunnel.js

@@ -37,6 +37,11 @@ function assertForwardSpec(node) {
   if (node.sshPort !== undefined && !store.isPort(node.sshPort)) throw new Error('tunnel: sshPort non valida');
   if (node.identityFile !== undefined && !store.isAbsPath(node.identityFile)) throw new Error('tunnel: identityFile non valido');
   if (node.keyPath !== undefined && !store.isAbsPath(node.keyPath)) throw new Error('tunnel: keyPath non valido');
+  if (node.reversePort !== undefined && !store.isPort(node.reversePort)) throw new Error('tunnel: reversePort non valida');
+  if (node.localAppPort !== undefined && !store.isPort(node.localAppPort)) throw new Error('tunnel: localAppPort non valida');
+  if (node.shared === true && node.reversePort !== undefined && !store.isPort(node.localAppPort)) {
+    throw new Error('tunnel: Share richiede localAppPort esplicita');
+  }
   if (!store.parseSshTarget(node.ssh)) throw new Error('tunnel: target ssh non valido');
 }
 
@@ -52,7 +57,7 @@ function buildForwardArgs(node) {
   // 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}`,
+    '-R', `127.0.0.1:${node.reversePort}:127.0.0.1:${node.localAppPort}`,
   ] : [];
   return SSH_BASE_OPTS.concat(transport, identity ? ['-i', identity] : [], [
     '-L', `127.0.0.1:${node.localPort}:127.0.0.1:${node.remotePort}`,
@@ -246,13 +251,23 @@ function removeStateIfOwned(home, name, meta) {
   return false;
 }
 
-function supervisorExited(pid, timeoutMs = 2500) {
+function supervisorExited(pid, timeoutMs = 2500, impl = {}) {
   const deadline = Date.now() + timeoutMs;
   const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  const pidExistsImpl = impl.pidExistsImpl || pidf.pidExists;
+  const procReadImpl = impl.procReadImpl || fs.readFileSync;
+  const spawnSyncImpl = impl.spawnSyncImpl || spawnSync;
   const exited = () => {
-    if (!pidf.pidExists(pid)) return true;
-    try { return fs.readFileSync(`/proc/${pid}/stat`, 'utf8').split(' ')[2] === 'Z'; }
-    catch (_) { return false; }
+    if (!pidExistsImpl(pid)) return true;
+    try { return procReadImpl(`/proc/${pid}/stat`, 'utf8').split(' ')[2] === 'Z'; }
+    catch (_) {
+      // macOS has no /proc. `ps` is argv-only and its STAT starts with Z for a
+      // zombie, which is no longer a usable supervisor even before wait/reap.
+      try {
+        const result = spawnSyncImpl('ps', ['-p', String(pid), '-o', 'stat='], { encoding: 'utf8' });
+        return !result?.error && /^Z/.test(String(result?.stdout || '').trim());
+      } catch (_error) { return false; }
+    }
   };
   while (!exited() && Date.now() < deadline) Atomics.wait(sleeper, 0, 0, 25);
   return exited();
@@ -418,7 +433,8 @@ function restartTunnel(opts) {
 // Helper di alto livello: costruisce args dal nodo e avvia il forward.
 function startForward(opts) {
   const node = opts.node;
-  const args = buildForwardArgs({ ...node, localAppPort: opts.localAppPort });
+  const localAppPort = opts.localAppPort === undefined ? node.localAppPort : opts.localAppPort;
+  const args = buildForwardArgs({ ...node, 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".

package/lib/proxy/federation.js

@@ -57,6 +57,8 @@ function knownResource(resource) {
     || resource === '/files'
     || resource === '/files/download'
     || resource === '/files/upload'
+    || resource === '/cells'
+    || resource === '/cells/send'
     || resource === '/decks'
     || /^\/decks\/[a-z0-9-]{1,32}$/.test(resource)
     || resource === '/topology'
@@ -65,7 +67,7 @@ function knownResource(resource) {
     // Hydra: the rest of /settings stays unreachable.
     || resource === '/settings/peering/invite'
     || resource === '/ws'
-    || /^\/fleet\/(status|schema|definitions|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells)$/.test(resource);
+    || /^\/fleet\/(status|schema|definitions|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource);
 }
 
 function allowedResource(resource, method = 'GET') {
@@ -76,6 +78,8 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/files') return method === 'GET' || method === 'DELETE';
   if (resource === '/files/download') return method === 'GET';
   if (resource === '/files/upload') return method === 'POST';
+  if (resource === '/cells') return method === 'GET';
+  if (resource === '/cells/send') return method === 'POST';
   if (resource === '/decks') return method === 'GET' || method === 'POST';
   if (/^\/decks\/[a-z0-9-]{1,32}$/.test(resource)) {
     return method === 'PUT' || method === 'PATCH' || method === 'DELETE';
@@ -84,7 +88,7 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/settings/peering/invite') return method === 'POST';
   if (resource === '/ws') return method === 'GET';
   if (/^\/fleet\/(status|schema|definitions)$/.test(resource)) return method === 'GET';
-  if (/^\/fleet\/(up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells)$/.test(resource)) return method === 'POST';
+  if (/^\/fleet\/(up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource)) return method === 'POST';
   return false;
 }
 
@@ -116,7 +120,12 @@ function routeHandler({ nodesPath, localPort, localCredential, ingress = null, r
     const visited = controlledVisited(req, ingress, st.nodeId);
     if (!visited) return res.status(409).json({ error: 'federation cycle rejected' });
     if (parsed.route.length === 0) {
-      return proxyHttp(req, res, { port: typeof localPort === 'function' ? localPort() : localPort, path: `/api${parsed.resource}${queryOf(req.url)}`, credential: localCredential() });
+      return proxyHttp(req, res, {
+        port: typeof localPort === 'function' ? localPort() : localPort,
+        path: `/api${parsed.resource}${queryOf(req.url)}`,
+        credential: localCredential(),
+        visited,
+      });
     }
     const next = st && store.getNode(st, parsed.route[0]);
     const privateInbound = next && next.direction === 'inbound' && next.shared !== true;
@@ -196,9 +205,37 @@ async function probeHealth({ port, token, expectedInstanceId = null, fetchImpl =
   return out;
 }
 
+// A freshly restarted SSH supervisor returns before both forwards are
+// necessarily accepting traffic.  Share must therefore wait for the actual
+// authenticated federation channel instead of racing a single immediate
+// fetch.  Auth/identity failures are terminal; transport startup is retried
+// for a short bounded window.
+async function waitForHealthyPeer(opts = {}) {
+  const attempts = Number.isInteger(opts.attempts) && opts.attempts > 0 ? Math.min(opts.attempts, 12) : 6;
+  const delayMs = Number.isInteger(opts.delayMs) && opts.delayMs >= 0 ? Math.min(opts.delayMs, 2000) : 200;
+  const delay = typeof opts.delay === 'function'
+    ? opts.delay : (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const probeOpts = { ...opts };
+  delete probeOpts.attempts; delete probeOpts.delayMs; delete probeOpts.delay;
+  let last = null;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    last = await probeHealth(probeOpts);
+    if (last.status === 'healthy') return last;
+    if (last.auth === 'failed' || /instanceId inatteso/.test(last.detail || '')) break;
+    if (attempt + 1 < attempts) await delay(delayMs);
+  }
+  return last || { status: 'down', detail: 'peer non raggiungibile' };
+}
+
 function controlledVisited(req, ingress, instanceId) {
   const raw = ingress ? String(req.headers['x-nexuscrew-visited'] || '') : '';
   const seen = raw ? raw.split(',').filter(Boolean) : [];
+  // On a peer-facing route the last server-controlled hop must be the peer
+  // authenticated by its scoped federation token.  Without this binding a
+  // token holder could forge the first visited ID and impersonate another
+  // cell-network sender at the destination.
+  if (ingress && (!store.NODE_ID_RE.test(String(ingress.nodeId || ''))
+    || !seen.length || seen.at(-1) !== ingress.nodeId)) return null;
   if (seen.some((id) => !store.NODE_ID_RE.test(id)) || seen.includes(instanceId) || seen.length > MAX_HOPS) return null;
   return [...seen, instanceId];
 }
@@ -320,11 +357,13 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
     }
     try {
       if (body.shared) {
-        const health = await probeHealth({
+        const health = await waitForHealthyPeer({
           port: req.peer.localPort,
           token: req.peer.token,
           expectedInstanceId: req.peer.nodeId || null,
           fetchImpl: fetchImpl || fetch,
+          attempts: 6,
+          delayMs: 200,
         });
         if (health.status !== 'healthy') {
           return res.status(409).json({
@@ -396,5 +435,5 @@ function reject(socket, code) { try { socket.end(`HTTP/1.1 ${code} Error\r\nConn
 module.exports = {
   MAX_HOPS, ROUTE_DELIMITER, peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource,
   collectTopology, collectTopologyDetailed, collectLocalTopology, peerRouter, localRouter, forwardUpgrade,
-  probeHealth,
+  probeHealth, waitForHealthyPeer,
 };

package/lib/pty/attach.js

@@ -2,6 +2,7 @@
 const { execFile } = require('node:child_process');
 const os = require('node:os');
 const { loadPty } = require('./provider.js');
+const { withUtf8Locale } = require('../runtime/env.js');
 
 // Opens `tmux attach` inside a real PTY, non-destructive for other clients.
 //
@@ -31,7 +32,7 @@ function openAttach(session, opts = {}) {
     name: 'xterm-256color',
     cols, rows,
     cwd: process.env.HOME || os.homedir(),
-    env: process.env,
+    env: withUtf8Locale(process.env),
   });
   // tty del client tmux (es. /dev/pts/N): identifica QUESTO client per la
   // promozione/demozione runtime del size-owner via `refresh-client -t <tty>`.
@@ -52,4 +53,4 @@ function openAttach(session, opts = {}) {
     demote: () => setFlags('ignore-size'),
   };
 }
-module.exports = { openAttach };
+module.exports = { openAttach, attachEnv: (env, platform) => withUtf8Locale(env, { platform }) };

package/lib/runtime/env.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const os = require('node:os');
+
+const MINIMAL_ENV_KEYS = Object.freeze([
+  'PATH', 'HOME', 'SHELL', 'TERM', 'COLORTERM', 'LANG', 'LANGUAGE',
+  'LC_ALL', 'LC_CTYPE', 'USER', 'LOGNAME', 'TMUX', 'TMUX_TMPDIR',
+  'XDG_RUNTIME_DIR', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME',
+  'DBUS_SESSION_BUS_ADDRESS',
+  // Termux/Android native clients need these to resolve their runtime, tmp and
+  // platform paths.  They are location metadata, never credentials.
+  'PREFIX', 'TMPDIR', 'TERMUX_VERSION', 'ANDROID_DATA', 'ANDROID_ROOT',
+]);
+
+const UTF8_RE = /utf-?8/i;
+
+function localeDefaults(platform = process.platform, env = process.env) {
+  const termux = platform === 'android' || String(env.PREFIX || '').includes('com.termux');
+  if (platform === 'darwin') return { lang: 'en_US.UTF-8', ctype: 'UTF-8' };
+  if (termux) return { lang: 'en_US.UTF-8', ctype: 'en_US.UTF-8' };
+  return { lang: 'C.UTF-8', ctype: 'C.UTF-8' };
+}
+
+function withUtf8Locale(source = process.env, { platform = process.platform } = {}) {
+  const env = { ...source };
+  const defaults = localeDefaults(platform, env);
+  const effective = env.LC_ALL || env.LC_CTYPE || env.LANG || '';
+  if (!UTF8_RE.test(effective)) {
+    if (env.LC_ALL) env.LC_ALL = defaults.lang;
+    env.LANG = defaults.lang;
+    env.LC_CTYPE = defaults.ctype;
+  } else {
+    if (!env.LANG) env.LANG = defaults.lang;
+    if (!env.LC_CTYPE) env.LC_CTYPE = env.LC_ALL || env.LANG || defaults.ctype;
+  }
+  if (!env.TERM) env.TERM = 'xterm-256color';
+  return env;
+}
+
+function minimalRuntimeEnv(source = process.env, opts = {}) {
+  const selected = {};
+  for (const key of MINIMAL_ENV_KEYS) {
+    if (source[key] !== undefined && source[key] !== '') selected[key] = String(source[key]);
+  }
+  if (!selected.PATH) selected.PATH = '/usr/local/bin:/usr/bin:/bin';
+  if (!selected.HOME) selected.HOME = opts.home || os.homedir();
+  return withUtf8Locale(selected, opts);
+}
+
+module.exports = { MINIMAL_ENV_KEYS, UTF8_RE, localeDefaults, withUtf8Locale, minimalRuntimeEnv };