@mmmbuto/nexuscrew 0.7.6 → 0.8.0

package/lib/cli/service.js

@@ -87,6 +87,10 @@ function generateMac(ctx) {
   const repoXml = escapeXml(ctx.repoRoot);
   const homeXml = escapeXml(ctx.home);
   const port = ctx.port;
+  const launchPath = [...new Set([
+    path.dirname(ctx.nodeBin), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin',
+  ])].join(':');
+  const launchPathXml = escapeXml(launchPath);
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -105,6 +109,8 @@ function generateMac(ctx) {
   <dict>
     <key>NEXUSCREW_PORT</key>
     <string>${port}</string>
+    <key>PATH</key>
+    <string>${launchPathXml}</string>
   </dict>
   <key>RunAtLoad</key>
   <true/>
@@ -193,7 +199,11 @@ function installService(platform, content, ctx, { dryRun = false, execImpl = exe
   const failures = [];
   for (const [bin, args] of cmds) {
     try { execImpl(bin, args, { stdio: 'ignore' }); }
-    catch (e) { failures.push({ cmd: `${bin} ${args.join(' ')}`, error: e.message }); }
+    catch (e) {
+      // bootout e' idempotente: un job non ancora caricato non e' un errore di installazione.
+      if (platform === 'mac' && bin === 'launchctl' && args[0] === 'bootout') continue;
+      failures.push({ cmd: `${bin} ${args.join(' ')}`, error: e.message });
+    }
   }
 
   return { target, mode, written: true, failures };
@@ -208,11 +218,12 @@ function installCommands(platform, target, ctx) {
     ];
   }
   if (platform === 'mac') {
-    const label = `gui/${ctx.uid || uid()}/com.mmmbuto.nexuscrew`;
+    const domain = `gui/${ctx.uid || uid()}`;
+    const label = `${domain}/com.mmmbuto.nexuscrew`;
     // bootout (ignore se non esiste) poi bootstrap
     return [
       ['launchctl', ['bootout', label]],
-      ['launchctl', ['bootstrap', label, target]],
+      ['launchctl', ['bootstrap', domain, target]],
     ];
   }
   if (platform === 'termux') {

package/lib/cli/url.js

@@ -0,0 +1,63 @@
+'use strict';
+// URL/token helpers per la CLI unificata (design §3). [A2]
+// - resolvePaths: config/token path home-aware (seam per test con HOME temporanea).
+// - readToken: legge il token esistente SENZA crearlo (no-follow symlink), null se assente.
+// - loadPort: porta corrente (opts > env > config.json > default 41820).
+// - buildUrl: URL loopback; withToken aggiunge #token=… (UNICO posto dove il token appare).
+// - renderQr: QR ASCII generato in locale (qrcode-terminal, MIT) — NIENTE fetch a runtime.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { readTokenSafe } = require('../auth/token.js');
+
+const DEFAULT_PORT = 41820;
+
+function resolvePaths(opts = {}) {
+  const home = opts.home || os.homedir();
+  const configDir = opts.configDir || path.join(home, '.nexuscrew');
+  return {
+    home,
+    configDir,
+    configPath: opts.configPath || path.join(configDir, 'config.json'),
+    tokenPath: opts.tokenPath || path.join(configDir, 'token'),
+  };
+}
+
+// Legge il token esistente (no create). Symlink -> throw (readTokenSafe); assente -> null.
+function readToken(tokenPath) {
+  try {
+    return readTokenSafe(tokenPath);
+  } catch (e) {
+    if (e.code === 'ENOENT') return null; // lstat su path inesistente
+    throw e; // symlink / permessi -> propaga
+  }
+}
+
+// Porta corrente: opts.port > env NEXUSCREW_PORT > config.json > default.
+function loadPort(opts = {}) {
+  if (opts.port) return Number(opts.port);
+  if (process.env.NEXUSCREW_PORT) return Number(process.env.NEXUSCREW_PORT);
+  const { configPath } = resolvePaths(opts);
+  try {
+    const c = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (c && c.port) return Number(c.port);
+  } catch (_) {}
+  return DEFAULT_PORT;
+}
+
+// URL loopback. withToken=true e token presente -> aggiunge #token=… (mai altrove).
+function buildUrl(port, token, { withToken = false } = {}) {
+  const base = `http://127.0.0.1:${port}/`;
+  return withToken && token ? `${base}#token=${token}` : base;
+}
+
+// QR ASCII del testo. Generazione locale (qrcode-terminal), callback sincrona.
+// small=true -> QR compatto (half-block chars) leggibile su terminale mobile/Termux.
+function renderQr(text, opts = {}) {
+  const qrcode = opts.qrcode || require('qrcode-terminal');
+  let out = '';
+  qrcode.generate(String(text), { small: opts.small !== false }, (s) => { out = s; });
+  return out;
+}
+
+module.exports = { resolvePaths, readToken, loadPort, buildUrl, renderQr, DEFAULT_PORT };

package/lib/config.js

@@ -20,6 +20,8 @@ function baseDefaults() {
     tokenPath: path.join(os.homedir(), '.nexuscrew', 'token'),
     tmuxBin: 'tmux',
     readonlyDefault: false,
+    // Etichetta neutra usata nel prefisso delle risposte ask incollate in TUI.
+    replyLabel: 'human',
     filesRoot: path.join(os.homedir(), 'NexusFiles'),
     maxUpload: 100 * 1024 * 1024,
     voiceUrl: null,
@@ -27,6 +29,7 @@ function baseDefaults() {
     voiceTokenFile: null,
     fleetEnabled: true,
     fleetBin: path.join(os.homedir(), '.local', 'bin', 'fleet'),
+    providerSecretsPath: path.join(os.homedir(), '.nexuscrew', 'providers.env'),
     sessionPresets: {},
   };
 }
@@ -51,6 +54,7 @@ function envOverrides() {
   if (process.env.NEXUSCREW_TOKEN_FILE) e.tokenPath = process.env.NEXUSCREW_TOKEN_FILE;
   if (process.env.NEXUSCREW_TMUX) e.tmuxBin = process.env.NEXUSCREW_TMUX;
   if (process.env.NEXUSCREW_READONLY) e.readonlyDefault = process.env.NEXUSCREW_READONLY === '1';
+  if (process.env.NEXUSCREW_REPLY_LABEL) e.replyLabel = process.env.NEXUSCREW_REPLY_LABEL;
   if (process.env.NEXUSCREW_FILES_ROOT) e.filesRoot = process.env.NEXUSCREW_FILES_ROOT;
   if (process.env.NEXUSCREW_MAX_UPLOAD_MB) e.maxUpload = Number(process.env.NEXUSCREW_MAX_UPLOAD_MB) * 1024 * 1024;
   if (process.env.NEXUSCREW_VOICE_URL) e.voiceUrl = process.env.NEXUSCREW_VOICE_URL;
@@ -58,6 +62,7 @@ function envOverrides() {
   if (process.env.NEXUSCREW_VOICE_TOKEN_FILE) e.voiceTokenFile = process.env.NEXUSCREW_VOICE_TOKEN_FILE;
   if (process.env.NEXUSCREW_FLEET) e.fleetEnabled = process.env.NEXUSCREW_FLEET !== '0';
   if (process.env.NEXUSCREW_FLEET_BIN) e.fleetBin = process.env.NEXUSCREW_FLEET_BIN;
+  if (process.env.NEXUSCREW_PROVIDER_SECRETS) e.providerSecretsPath = process.env.NEXUSCREW_PROVIDER_SECRETS;
   return e;
 }
 

package/lib/decks/routes.js

@@ -0,0 +1,81 @@
+'use strict';
+const express = require('express');
+const fs = require('node:fs');
+const store = require('./store.js');
+
+function httpError(status, message, extra) {
+  const e = new Error(message); e.status = status; e.extra = extra; return e;
+}
+
+function decksRoutes({ cfg = {}, decksPath }) {
+  const r = express.Router();
+  r.use(express.json({ limit: '64kb' }));
+  const readonly = () => cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1';
+  const mutate = (fn) => (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: mutazione deck bloccata' });
+    try { return fn(req, res); }
+    catch (e) { return res.status(e.status || 500).json({ error: String(e.message || e), ...(e.extra || {}) }); }
+  };
+  const read = () => {
+    const found = store.loadStore(decksPath);
+    if (found) return found;
+    if (readonly() && !fs.existsSync(decksPath)) return store.emptyStore();
+    return store.loadOrCreate(decksPath);
+  };
+  const expected = (body) => {
+    const n = body && body.expectedRevision;
+    if (!Number.isSafeInteger(n) || n < 0) throw httpError(400, 'expectedRevision non valida');
+    return n;
+  };
+  const find = (st, name) => st.decks.find((d) => d.name === name) || null;
+  const checkRevision = (deck, rev) => {
+    if (deck.revision !== rev) throw httpError(409, 'deck modificato da un’altra finestra', { current: deck });
+  };
+
+  r.get('/', (_req, res) => {
+    try { res.json(read()); } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+  r.post('/', mutate((req, res) => {
+    const name = String(req.body && req.body.name || '');
+    if (!store.NAME_RE.test(name)) throw httpError(400, 'nome deck non valido');
+    const st = read();
+    if (find(st, name)) throw httpError(409, `deck già esistente: ${name}`);
+    if (st.decks.length >= store.MAX_DECKS) throw httpError(400, 'limite deck raggiunto');
+    const deck = { name, revision: 0, layout: { columns: [] } };
+    st.decks.push(deck); store.atomicWrite(decksPath, st);
+    res.status(201).json(deck);
+  }));
+  r.put('/:name', mutate((req, res) => {
+    const st = read(); const deck = find(st, String(req.params.name || ''));
+    if (!deck) throw httpError(404, 'deck inesistente');
+    checkRevision(deck, expected(req.body));
+    const layout = store.parseLayout(req.body && req.body.layout);
+    if (!layout) throw httpError(400, 'layout deck non valido');
+    deck.layout = layout; deck.revision += 1;
+    store.atomicWrite(decksPath, st); res.json(deck);
+  }));
+  r.patch('/:name', mutate((req, res) => {
+    const oldName = String(req.params.name || '');
+    if (oldName === 'main') throw httpError(400, 'main non rinominabile');
+    const newName = String(req.body && req.body.name || '');
+    if (!store.NAME_RE.test(newName)) throw httpError(400, 'nome deck non valido');
+    const st = read(); const deck = find(st, oldName);
+    if (!deck) throw httpError(404, 'deck inesistente');
+    checkRevision(deck, expected(req.body));
+    if (find(st, newName)) throw httpError(409, `deck già esistente: ${newName}`);
+    deck.name = newName; deck.revision += 1;
+    store.atomicWrite(decksPath, st); res.json(deck);
+  }));
+  r.delete('/:name', mutate((req, res) => {
+    const name = String(req.params.name || '');
+    if (name === 'main') throw httpError(400, 'main non eliminabile');
+    const st = read(); const deck = find(st, name);
+    if (!deck) throw httpError(404, 'deck inesistente');
+    checkRevision(deck, expected(req.body));
+    st.decks = st.decks.filter((d) => d.name !== name);
+    store.atomicWrite(decksPath, st); res.json({ removed: true, name });
+  }));
+  return r;
+}
+
+module.exports = { decksRoutes };

package/lib/decks/store.js

@@ -0,0 +1,117 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const SCHEMA_VERSION = 1;
+const MAX_DECKS = 24;
+const MAX_TILES = 9;
+const NAME_RE = /^[a-z0-9-]{1,32}$/;
+const NODE_RE = /^[a-z0-9-]{1,32}$/;
+
+function defaultDecksPath(home) {
+  return path.join(home || os.homedir(), '.nexuscrew', 'decks.json');
+}
+
+function emptyLayout() { return { columns: [] }; }
+function emptyStore() {
+  return { schemaVersion: SCHEMA_VERSION, decks: [{ name: 'main', revision: 0, layout: emptyLayout() }] };
+}
+
+function validText(s, max) {
+  if (typeof s !== 'string' || !s || s.length > max) return false;
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s.charCodeAt(i);
+    if (c <= 0x1f || c === 0x7f) return false;
+  }
+  return true;
+}
+
+function parseLayout(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !Array.isArray(raw.columns)) return null;
+  if (raw.columns.length > MAX_TILES) return null;
+  const seen = new Set();
+  const columns = [];
+  let count = 0;
+  for (const c of raw.columns) {
+    if (!c || typeof c !== 'object' || Array.isArray(c) || !Array.isArray(c.tiles) || !c.tiles.length) return null;
+    const width = Number(c.width);
+    if (!Number.isFinite(width) || width < 0.2 || width > 100) return null;
+    const tiles = [];
+    for (const t of c.tiles) {
+      if (!t || typeof t !== 'object' || Array.isArray(t) || !validText(t.session, 128)) return null;
+      if (t.node !== undefined && (typeof t.node !== 'string' || !NODE_RE.test(t.node))) return null;
+      const height = Number(t.height);
+      const fontSize = Number(t.fontSize);
+      if (!Number.isFinite(height) || height < 0.2 || height > 100) return null;
+      if (!Number.isFinite(fontSize) || fontSize < 9 || fontSize > 24) return null;
+      const key = t.node ? `${t.node}:${t.session}` : t.session;
+      if (seen.has(key) || ++count > MAX_TILES) return null;
+      seen.add(key);
+      const tile = { session: t.session, height, fontSize };
+      if (t.node) tile.node = t.node;
+      tiles.push(tile);
+    }
+    columns.push({ width, tiles });
+  }
+  return { columns };
+}
+
+function parseStore(raw) {
+  try {
+    const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)
+      || obj.schemaVersion !== SCHEMA_VERSION || !Array.isArray(obj.decks)
+      || obj.decks.length < 1 || obj.decks.length > MAX_DECKS) return null;
+    const names = new Set();
+    const decks = [];
+    for (const d of obj.decks) {
+      if (!d || typeof d !== 'object' || !NAME_RE.test(d.name) || names.has(d.name)) return null;
+      if (!Number.isSafeInteger(d.revision) || d.revision < 0) return null;
+      const layout = parseLayout(d.layout);
+      if (!layout) return null;
+      names.add(d.name);
+      decks.push({ name: d.name, revision: d.revision, layout });
+    }
+    if (!names.has('main')) return null;
+    decks.sort((a, b) => (a.name === 'main' ? -1 : b.name === 'main' ? 1 : a.name.localeCompare(b.name)));
+    return { schemaVersion: SCHEMA_VERSION, decks };
+  } catch (_) { return null; }
+}
+
+function loadStore(p) {
+  try {
+    const st = fs.lstatSync(p);
+    if (!st.isFile() || st.isSymbolicLink()) return null;
+    return parseStore(fs.readFileSync(p, 'utf8'));
+  } catch (_) { return null; }
+}
+
+function atomicWrite(p, data) {
+  try {
+    if (fs.lstatSync(p).isSymbolicLink()) throw new Error('refuse symlink decks.json');
+  } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  const parsed = parseStore(data);
+  if (!parsed) throw new Error('decks.json non valido');
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = path.join(path.dirname(p), `.${path.basename(p)}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, p);
+  } catch (e) { try { fs.unlinkSync(tmp); } catch (_) {} throw e; }
+  return parsed;
+}
+
+function loadOrCreate(p) {
+  const found = loadStore(p);
+  if (found) return found;
+  try { if (fs.existsSync(p)) throw new Error('decks.json presente ma invalido'); } catch (e) { throw e; }
+  return atomicWrite(p, emptyStore());
+}
+
+module.exports = {
+  SCHEMA_VERSION, MAX_DECKS, MAX_TILES, NAME_RE,
+  defaultDecksPath, emptyStore, parseLayout, parseStore, loadStore, loadOrCreate, atomicWrite,
+};

package/lib/files/routes.js

@@ -1,10 +1,15 @@
 'use strict';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const express = require('express');
 const { Router } = require('express');
 const multer = require('multer');
 const store = require('./store.js');
 
 // Router file-exchange. Nessuno stato: tutto deriva da cfg + filesystem.
-function filesRoutes({ cfg, sessionExists, paste }) {
+// notifier (opzionale, MCP bridge): emette la notify di consegna file outbox.
+function filesRoutes({ cfg, sessionExists, paste, notifier }) {
   const router = Router();
   const upload = multer({
     storage: multer.memoryStorage(),
@@ -23,11 +28,63 @@ function filesRoutes({ cfg, sessionExists, paste }) {
         return res.status(404).json({ error: 'sessione tmux inesistente' });
       }
       const saved = store.saveUpload(cfg.filesRoot, session, req.file.buffer, req.file.originalname);
-      const pasted = await paste(session, saved.path);
+      // paste=false (tasto allegati del composer): il client appende il path al
+      // testo del composer — niente scrittura PTY. Default = incolla (FilesPanel).
+      const wantPaste = String((req.body && req.body.paste) || '') !== 'false';
+      const pasted = wantPaste ? await paste(session, saved.path) : false;
       res.json({ ...saved, pasted });
     });
   });
 
+  // Consegna deliverable dal MCP bridge (nc_send_file): copia un file locale
+  // nell'outbox della sessione mittente. Path sorgente fail-closed: stringa
+  // assoluta, realpath ESISTENTE sotto HOME (i symlink si risolvono PRIMA del
+  // check: un link che esce da HOME viene rifiutato), file regolare.
+  // F3 (audit): gated READONLY — la copia e' una scrittura su disco; il gate
+  // sta PRIMA di ogni altro check (nessun probe di sessione/path in READONLY).
+  const bridgeReadonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
+  router.post('/outbox', express.json({ limit: '8kb' }), (req, res) => {
+    try {
+      if (bridgeReadonly()) {
+        return res.status(403).json({ error: 'READONLY: consegna file bloccata' });
+      }
+      const b = req.body || {};
+      const session = String(b.session || '');
+      if (!store.isValidSession(session) || !sessionExists(session)) {
+        return res.status(404).json({ error: 'sessione tmux inesistente' });
+      }
+      if (typeof b.path !== 'string' || !path.isAbsolute(b.path)) {
+        return res.status(400).json({ error: 'path deve essere assoluto' });
+      }
+      if (b.caption !== undefined && (typeof b.caption !== 'string' || b.caption.length > 500)) {
+        return res.status(400).json({ error: 'caption deve essere una stringa (max 500)' });
+      }
+      const home = cfg.home || os.homedir();
+      let src;
+      try { src = fs.realpathSync(b.path); } catch (_) {
+        return res.status(404).json({ error: 'file sorgente inesistente' });
+      }
+      const homeReal = fs.realpathSync(home);
+      if (src !== homeReal && !src.startsWith(homeReal + path.sep)) {
+        return res.status(400).json({ error: 'path fuori da HOME' });
+      }
+      if (!fs.statSync(src).isFile()) {
+        return res.status(400).json({ error: 'path non e\' un file regolare' });
+      }
+      const saved = store.saveDeliverable(cfg.filesRoot, session, src);
+      if (!saved) return res.status(400).json({ error: 'sessione invalida' });
+      // Notify best-effort (il badge outbox lo genera comunque il watcher).
+      if (notifier) {
+        notifier.emit({
+          title: `file da ${session}`,
+          body: b.caption ? `${saved.name} — ${b.caption}` : saved.name,
+          session,
+        }).catch(() => {});
+      }
+      res.json({ name: saved.name, box: 'outbox', size: saved.size });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
   router.get('/', (req, res) => {
     const session = String(req.query.session || '');
     if (!store.isValidSession(session)) return res.status(400).json({ error: 'sessione invalida' });

package/lib/files/store.js

@@ -77,6 +77,21 @@ function saveUpload(root, session, buffer, origName, now = new Date()) {
   return { name, path: full, size: buffer.length };
 }
 
+// Consegna MCP bridge: copia un file gia' su disco nell'outbox della sessione
+// (badge/watcher scattano da soli). Naming identico a saveUpload (stamp +
+// sanitize + dedup) e COPYFILE_EXCL: mai overwrite. La validazione del path
+// sorgente (assoluto, sotto HOME, realpath) sta nella route, non qui.
+function saveDeliverable(root, session, srcPath, now = new Date()) {
+  const dir = ensureBox(root, session, 'outbox');
+  if (!dir) return null;
+  const base = `${stamp(now)}_${sanitizeName(path.basename(srcPath))}`;
+  let name = base;
+  for (let i = 1; fs.existsSync(path.join(dir, name)); i += 1) name = `${i}-${base}`;
+  const full = path.join(dir, name);
+  fs.copyFileSync(srcPath, full, fs.constants.COPYFILE_EXCL);
+  return { name, path: full, size: fs.statSync(full).size };
+}
+
 function listBox(root, session, box) {
   const dir = boxDir(root, session, box);
   if (!dir) return null;
@@ -123,5 +138,5 @@ function removeFile(root, session, box, name) {
 
 module.exports = {
   isValidSession, sanitizeName, stamp, boxDir, ensureBox,
-  saveUpload, listBox, resolveExisting, removeFile, BOXES,
+  saveUpload, saveDeliverable, listBox, resolveExisting, removeFile, BOXES,
 };

package/lib/fleet/boot.js

@@ -0,0 +1,62 @@
+'use strict';
+// B4.3 — Service companion boot. bootCells(fleet, {log}) avvia tutte le celle
+// boot:true di un fleet provider (builtin) chiamandone up(). Una cella gia' in
+// esecuzione (up -> httpError 409 / "duplicate session") = SKIP non fatale;
+// ogni altro errore viene raccolto in failed[] e NON ferma le altre celle.
+// Nessun side-effect all'import. Design §4c / §9b.
+//
+// Agnostico: usa solo il contratto fleet {available, status(), up()} — non legge
+// internals delle definizioni. La lista delle celle boot:true arriva da status()
+// (campo `boot` derivato dalle definitions), cosi' un fleet esterno compatibile
+// potra' riusare la stessa funzione.
+
+const SKIP_STATUS = 409; // up() del builtin lancia httpError(409) su sessione duplicata
+
+async function bootCells(fleet, { log = () => {} } = {}) {
+  const started = [];
+  const skipped = [];
+  const failed = [];
+
+  if (!fleet || fleet.available === false) {
+    // provider non disponibile: niente da avviare. Il caller (runFleetBoot)
+    // filtra gia' mode==='builtin' (= fleet.available); qui e' solo defense-in-depth.
+    return { started, skipped, failed };
+  }
+
+  let cells = [];
+  try {
+    const st = await fleet.status();
+    cells = (st && Array.isArray(st.cells)) ? st.cells : [];
+  } catch (e) {
+    // status e' una lettura: se fallisce non possiamo sapere cosa avviare.
+    // Riportiamo come fallimento globale senza processare alcuna cella.
+    failed.push({ cell: '*', reason: `status() failed: ${e && e.message ? e.message : e}` });
+    return { started, skipped, failed };
+  }
+
+  for (const c of cells) {
+    if (!c || !c.boot) continue;            // solo boot:true
+    const id = c.cell;
+    try {
+      await fleet.up(id);
+      started.push(id);
+      log(`fleet-boot: started ${id}`);
+    } catch (e) {
+      const status = e && typeof e.status === 'number' ? e.status : null;
+      const reason = (e && e.message) ? e.message : String(e);
+      // gia' in esecuzione: skip non fatale (contratto builtin: 409/duplicate).
+      // Il regex copre anche fleet esterni che lanciano un Error generico.
+      if (status === SKIP_STATUS || /duplicate session|già in esecuzione/i.test(reason)) {
+        skipped.push(id);
+        log(`fleet-boot: skipped ${id} (already running)`);
+      } else {
+        failed.push({ cell: id, reason });
+        log(`fleet-boot: failed ${id} — ${reason}`);
+      }
+    }
+  }
+
+  return { started, skipped, failed };
+}
+
+module.exports = { bootCells };