@mmmbuto/nexuscrew 0.8.12 → 0.8.14

package/lib/fleet/launch-broker.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const fs = require('node:fs');
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const MAX_PAYLOAD = 512 * 1024;
+const REQUEST_LIMIT = 256;
+
+function runtimeDir(cfg = {}) {
+  const home = cfg.home || os.homedir();
+  return cfg.launchRuntimeDir || path.join(home, '.nexuscrew', 'run');
+}
+
+function ensureRuntimeDir(dir) {
+  const parent = path.dirname(dir);
+  try {
+    const parentSt = fs.lstatSync(parent);
+    const owned = typeof process.getuid !== 'function' || parentSt.uid === process.getuid();
+    if (!parentSt.isSymbolicLink() && parentSt.isDirectory() && owned && (parentSt.mode & 0o077)) {
+      fs.chmodSync(parent, 0o700);
+    }
+    const checked = fs.lstatSync(parent);
+    if (checked.isSymbolicLink() || !checked.isDirectory()
+      || (typeof process.getuid === 'function' && checked.uid !== process.getuid()) || (checked.mode & 0o077)) {
+      throw new Error('unsafe launch broker parent directory');
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const grand = fs.lstatSync(path.dirname(parent));
+    if (grand.isSymbolicLink() || !grand.isDirectory()
+      || (typeof process.getuid === 'function' && grand.uid !== process.getuid()) || (grand.mode & 0o022)) {
+      throw new Error('unsafe launch broker parent root');
+    }
+    fs.mkdirSync(parent, { mode: 0o700 });
+  }
+  try {
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()
+      || (typeof process.getuid === 'function' && st.uid !== process.getuid()) || (st.mode & 0o077)) {
+      throw new Error('unsafe launch broker directory');
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    fs.mkdirSync(dir, { mode: 0o700 });
+  }
+}
+
+function encodePayload(payload) {
+  const body = Buffer.from(JSON.stringify(payload), 'utf8');
+  if (!body.length || body.length > MAX_PAYLOAD) throw new Error('launch payload too large');
+  const head = Buffer.allocUnsafe(4); head.writeUInt32BE(body.length, 0);
+  return Buffer.concat([head, body]);
+}
+
+function createLaunchBroker(cfg = {}) {
+  const dir = runtimeDir(cfg);
+  let server = null;
+  let socketPath = '';
+  let starting = null;
+  let closed = false;
+  const pending = new Map();
+  const ttlMs = Math.max(1000, Number(cfg.launchTokenTtlMs) || 15000);
+
+  function expire(nonce) {
+    const entry = pending.get(nonce);
+    if (!entry) return;
+    pending.delete(nonce);
+    clearTimeout(entry.timer);
+  }
+
+  async function start() {
+    if (closed) throw new Error('launch broker closed');
+    if (server) return socketPath;
+    if (starting) return starting;
+    starting = new Promise((resolve, reject) => {
+      try {
+        ensureRuntimeDir(dir);
+        socketPath = path.join(dir, `launch-${process.pid}-${crypto.randomBytes(5).toString('hex')}.sock`);
+      } catch (error) { reject(error); return; }
+      server = net.createServer((socket) => {
+        let raw = '';
+        socket.setEncoding('utf8');
+        socket.setTimeout(3000, () => socket.destroy());
+        socket.on('data', (chunk) => {
+          raw += chunk;
+          if (raw.length > REQUEST_LIMIT) return socket.destroy();
+          const nl = raw.indexOf('\n');
+          if (nl === -1) return;
+          let nonce = '';
+          try { nonce = JSON.parse(raw.slice(0, nl)).nonce; } catch (_) {}
+          if (typeof nonce !== 'string' || !/^[a-f0-9]{64}$/.test(nonce)) return socket.destroy();
+          const entry = pending.get(nonce);
+          if (!entry || entry.expires < Date.now()) { expire(nonce); return socket.destroy(); }
+          // Single-use before any bytes leave this process. A second client can
+          // never claim the same payload, even while the first socket drains.
+          pending.delete(nonce); clearTimeout(entry.timer);
+          try { socket.end(entry.encoded); } catch (_) { socket.destroy(); }
+        });
+      });
+      server.once('error', (error) => {
+        if (!server?.listening) { server = null; starting = null; reject(error); }
+      });
+      server.listen(socketPath, () => {
+        try { fs.chmodSync(socketPath, 0o600); } catch (_) {}
+        server.unref(); starting = null; resolve(socketPath);
+      });
+    });
+    return starting;
+  }
+
+  async function issue(payload) {
+    const target = await start();
+    const nonce = crypto.randomBytes(32).toString('hex');
+    const entry = { encoded: encodePayload(payload), expires: Date.now() + ttlMs, timer: null };
+    entry.timer = setTimeout(() => expire(nonce), ttlMs);
+    entry.timer.unref?.();
+    pending.set(nonce, entry);
+    return { socketPath: target, nonce };
+  }
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    for (const [nonce] of pending) expire(nonce);
+    const active = server; server = null;
+    if (active) await new Promise((resolve) => active.close(() => resolve()));
+    try { if (socketPath) fs.unlinkSync(socketPath); } catch (_) {}
+  }
+
+  return { issue, close, pendingCount: () => pending.size };
+}
+
+module.exports = { createLaunchBroker, runtimeDir, ensureRuntimeDir, encodePayload, MAX_PAYLOAD };

package/lib/fleet/managed.js

@@ -6,6 +6,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { execFile } = require('node:child_process');
+const { ENV_KEY_RE } = require('./env-key.js');
+const { readCredentialStore } = require('./credentials.js');
 
 const OLLAMA_CLOUD_MODELS = Object.freeze([
   'glm-5.2', 'kimi-k2.7-code', 'deepseek-v4-pro', 'minimax-m3',
@@ -20,7 +22,6 @@ const OLLAMA_CONTEXT = Object.freeze({
 const CUSTOM_KEYS = ['displayName', 'protocol', 'baseUrl', 'envKey', 'providerId'];
 const MANAGED_KEYS = new Set(['client', 'provider', 'credentialProfile', 'model', 'permissionPolicy', ...CUSTOM_KEYS]);
 const CLIENT_LABELS = Object.freeze({ claude: 'Claude Code', codex: 'Codex', 'codex-vl': 'Codex-VL', pi: 'Pi' });
-const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
 const PROVIDER_ID_RE = /^[a-z][a-z0-9_-]{0,31}$/;
 
 function validBaseUrl(value) {
@@ -140,24 +141,65 @@ 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|\$(?:\{[A-Za-z_][A-Za-z0-9_]*\}|[A-Za-z_][A-Za-z0-9_]*)/.test(v)) continue;
     out[m[1]] = v;
   }
   return out;
 }
 
+function insideRoot(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function safeAllowedRoots(roots = []) {
+  const out = [];
+  for (const root of roots) {
+    try {
+      const st = fs.lstatSync(root);
+      if (st.isSymbolicLink() || !st.isDirectory() || (st.mode & 0o022)) continue;
+      if (typeof process.getuid === 'function' && st.uid !== process.getuid()) continue;
+      out.push(fs.realpathSync(root));
+    } catch (_) {}
+  }
+  return out;
+}
+
+function parseEnvFile(file, opts = {}) {
+  try {
+    const lst = fs.lstatSync(file);
+    let target = file;
+    if (lst.isSymbolicLink()) {
+      const roots = safeAllowedRoots(opts.allowSymlinkRoots);
+      if (!roots.length) return {};
+      target = fs.realpathSync(file);
+      if (!roots.some((root) => insideRoot(root, target))) return {};
+    }
+    const st = fs.lstatSync(target);
+    if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o077) || st.size > 256 * 1024) return {};
+    if (typeof process.getuid === 'function' && st.uid !== process.getuid()) return {};
+    return parseAssignments(fs.readFileSync(target, '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,18 +222,82 @@ 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 providerKeyPaths(cfg, home) {
+  const paths = [
+    cfg.providerKeysPath || process.env.NEXUSCREW_PROVIDER_KEYS
+      || path.join(home, '.config', 'keys', 'ai.env'),
+    cfg.providerSecurePath || process.env.NEXUSCREW_PROVIDER_SECURE
+      || path.join(home, '.config', 'secure', '.env'),
+  ];
+  return [...new Set(paths.filter((file) => typeof file === 'string' && file))];
+}
+
+function parseProviderKeyFiles(cfg, home) {
+  const values = {};
+  // Match providers.zsh ordering: a later secure file may intentionally
+  // override the canonical ai.env value. Files remain data-only and must be
+  // private regular files owned by the NexusCrew user.
+  const files = providerKeyPaths(cfg, home);
+  const roots = [...new Set(files.map((file) => path.dirname(path.resolve(file))))];
+  for (const file of files) Object.assign(values, parseEnvFile(file, { allowSymlinkRoots: roots }));
+  return values;
+}
+
+function credentialSources(cfg, home) {
+  let local = {};
+  try { local = readCredentialStore(cfg, home); } catch (_) { /* unsafe/corrupt store is ignored, never trusted */ }
+  return {
+    runtime: cfg.env || process.env,
+    local,
+    shell: parseProviderShellFile(shellProvidersPath(cfg, home)),
+    keys: parseProviderKeyFiles(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: '' };
+  if (profile.auth === 'login' || profile.auth === 'none') return { envKey: profile.auth, value: '', source: profile.auth };
   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] || '';
-  return { envKey, value };
+  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.
+  if (sources.runtime[envKey]) return { envKey, value: sources.runtime[envKey], source: 'environment' };
+  if (sources.local[envKey]) return { envKey, value: sources.local[envKey], source: 'local' };
+  if (sources.shell[envKey]) return { envKey, value: sources.shell[envKey], source: 'compatibility' };
+  if (sources.keys[envKey]) return { envKey, value: sources.keys[envKey], source: 'compatibility' };
+  if (profile.legacySecrets && sources.legacy[envKey]) {
+    return { envKey, value: sources.legacy[envKey], source: 'compatibility' };
+  }
+  return { envKey, value: '', source: 'missing' };
 }
 
 let ollamaCache = { at: 0, models: [] };
@@ -202,7 +308,10 @@ 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.local.OLLAMA_API_KEY || sources.shell.OLLAMA_API_KEY || sources.keys.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}`);
@@ -270,9 +379,12 @@ function describeManaged(spec, cfg = {}) {
     credentialProfile: normalized.credentialProfile || '', model: normalized.model,
     permissionPolicy: normalized.permissionPolicy, protocol: normalized.protocol || profile.protocol,
     endpoint: normalized.baseUrl || profile.endpoint || '', auth: cred.envKey, authConfigured,
+    credentialSource: authConfigured ? cred.source : 'missing',
     configured: !!binary && authConfigured, models: [...(profile.models || [])], defaultModel: profile.model || '',
     binary: binary || '', displayName: normalized.displayName || profile.label,
-    reason: !binary ? `client ${profile.client} not found` : (!authConfigured ? `environment variable ${cred.envKey} missing` : 'ready'),
+    reason: !binary ? `client ${profile.client} not found` : (!authConfigured
+      ? `credential ${cred.envKey} missing — set it on this device`
+      : 'ready'),
   };
 }
 
@@ -393,7 +505,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 +529,7 @@ 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,
+  providerKeyPaths, parseProviderKeyFiles, credentialSources, credential, ENV_KEY_RE,
 };

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');
 
@@ -106,6 +106,16 @@ function fleetRoutes(fleetP, cfg = {}) {
   // Ogni route negozia la capability del provider: mancante → 501 (§9c).
   r.get('/schema', guard((f) => { requireCap(f, 'schema'); return f.schema(); }));
   r.get('/definitions', guard((f) => { requireCap(f, 'definitions'); return f.definitions(); }));
+  r.get('/credentials/status', guard((f) => {
+    requireCap(f, 'credentials'); return f.credentialStatus();
+  }));
+  r.post('/credentials/set', guard((f, b) => {
+    requireCap(f, 'credentials');
+    return f.setLocalCredential(String(b.envKey || ''), typeof b.value === 'string' ? b.value : '');
+  }, { mutate: true }));
+  r.post('/credentials/remove', guard((f, b) => {
+    requireCap(f, 'credentials'); return f.removeLocalCredential(String(b.envKey || ''));
+  }, { mutate: true }));
   r.post('/define-engine', guard((f, b) => { requireCap(f, 'define'); return f.defineEngine(b.def); }, { mutate: true }));
   r.post('/edit-engine', guard((f, b) => { requireCap(f, 'edit'); return f.editEngine(b.id, b.patch, b.envChanges); }, { mutate: true }));
   r.post('/remove-engine', guard((f, b) => { requireCap(f, 'remove'); return f.removeEngine(b.id); }, { mutate: true }));
@@ -113,6 +123,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,
+};