@mmmbuto/nexuscrew 0.8.57 → 0.9.0

package/lib/fleet/cell-lease.js

@@ -0,0 +1,112 @@
+'use strict';
+
+// Pure state transitions for the supervisor lease of a Live host cell.
+//
+// Contratto rev12 R3 + rev13 S3 + rev22. Il canale lease e' la connessione UDS
+// accettata col nonce one-shot del launch-broker che RESTA APERTA dopo il frame
+// payload (R3.1.1); dopo un EOF il supervisore si riconnette a un endpoint
+// stabile (R3.3.2). Qui vivono SOLO le transizioni di stato del lease: i side
+// effect (socket, timer, EOF handling) stanno nel LeaseManager e nei caller.
+// Modello speculare a lib/nodes/reverse-rotation.js (clone + arg validation),
+// cosi' i casi crash/replay sono espliciti e testabili senza socket.
+//
+// Invarianti normativi ribaditi nel codice:
+//  - EOF arma UNA sola transizione monotona Live -> Grace (R3.1.3); la deadline
+//    e' non estendibile: un secondo armGrace su un lease in Grace e' no-op.
+//  - Nessuna operazione riporta in Live un lease gia' in Grace: refresh e armGrace
+//    non cambiano lo stato di un lease in Grace. Solo reattach crea un lease NUOVO.
+//  - reattach (R3.3.4) produce un lease con leaseId NUOVO e STESSA identita'
+//    cellId+launchEpoch (la generation puo' avanzare). Non e' la resurrezione del
+//    lease precedente: il vecchio lease resta nella sua grace, la monotonia
+//    per-lease resta intatta e la vecchia deadline diventa irrilevante.
+//  - Oltre la grace il reconnect e' rifiutato (R3.3.5): reattach di un lease
+//    scaduto restituisce null.
+
+const crypto = require('node:crypto');
+
+const GRACE_MS = 60_000;             // R3.2: grace 60s dall'EOF, non estendibile
+const REFRESH_MS = 20_000;           // R3.2: cadenza refresh 20s (heartbeat lato supervisore)
+const RECONNECT_CADENCE_MS = 20_000; // rev13 S3.3: >=2 tentativi strettamente dentro la grace
+
+function isInt(v) { return Number.isSafeInteger(v); }
+function validId(v, max = 128) { return typeof v === 'string' && v.length > 0 && v.length <= max; }
+function validLeaseId(v) { return typeof v === 'string' && /^[a-f0-9]{16,64}$/.test(v); }
+
+function newLeaseId() { return crypto.randomBytes(16).toString('hex'); }
+
+// Apertura del lease: prima connessione (post-payload). Nasce Live, senza grace.
+function openLease({ cellId, launchEpoch, generation, leaseId, now }) {
+  if (!validId(cellId) || !validId(launchEpoch) || !isInt(generation) || generation < 0
+    || !validLeaseId(leaseId) || !isInt(now)) return null;
+  return {
+    cellId, launchEpoch, generation, leaseId,
+    state: 'live',
+    openedAt: now,
+    lastRefreshedAt: now,
+    eofArmedAt: null,
+    graceDeadline: null,
+  };
+}
+
+// EOF arma UNA sola transizione monotona Live -> Grace. Su un lease gia' in Grace
+// e' no-op (ritorna lo stesso lease): la deadline NON si estende (R3.1.3).
+function armGrace(lease, { now } = {}) {
+  if (!lease || !isInt(now)) return null;
+  if (lease.state === 'grace') return lease;
+  const next = { ...lease };
+  next.state = 'grace';
+  next.eofArmedAt = now;
+  next.graceDeadline = now + GRACE_MS;
+  return next;
+}
+
+// Refresh: heartbeat lato supervisore (cad 20s). Aggiorna lastRefreshedAt. NON
+// cambia state e NON riporta in Live un lease in Grace (R3.1.3). Hook per la
+// rotazione del proof HMAC (fetta 2b); in 2a e' solo liveness applicativa + ack.
+function refresh(lease, { now } = {}) {
+  if (!lease || !isInt(now)) return null;
+  return { ...lease, lastRefreshedAt: now };
+}
+
+// Reconnect riuscito (R3.3.4): lease NUOVO (leaseId nuovo), STESSA identita'
+// cellId+launchEpoch (la generation puo' avanzare), state Live. R3.3.5: oltre la
+// grace il reconnect e' rifiutato -> null. Il vecchio lease resta nella sua grace.
+function reattach(lease, { leaseId, generation, now } = {}) {
+  if (!lease || !validLeaseId(leaseId) || !isInt(generation) || generation < 0 || !isInt(now)) return null;
+  if (lease.state === 'grace' && now >= lease.graceDeadline) return null;
+  return {
+    cellId: lease.cellId,
+    launchEpoch: lease.launchEpoch,
+    generation,
+    leaseId,
+    state: 'live',
+    openedAt: now,
+    lastRefreshedAt: now,
+    eofArmedAt: null,
+    graceDeadline: null,
+  };
+}
+
+function isLive(lease) {
+  return !!lease && lease.state === 'live';
+}
+
+function isGrace(lease, { now = Date.now() } = {}) {
+  return !!lease && lease.state === 'grace' && isInt(now) && lease.graceDeadline != null && now < lease.graceDeadline;
+}
+
+function isExpired(lease, { now = Date.now() } = {}) {
+  return !!lease && lease.state === 'grace' && isInt(now) && lease.graceDeadline != null && now >= lease.graceDeadline;
+}
+
+// Chiave composita di identita' per la map lato server (modello rotatableReverse).
+function identityKey(cellId, launchEpoch, generation) {
+  if (!validId(cellId) || !validId(launchEpoch) || !isInt(generation) || generation < 0) return null;
+  return `${cellId}:${launchEpoch}:${generation}`;
+}
+
+module.exports = {
+  GRACE_MS, REFRESH_MS, RECONNECT_CADENCE_MS,
+  newLeaseId, openLease, armGrace, refresh, reattach,
+  isLive, isGrace, isExpired, identityKey,
+};

package/lib/fleet/definitions.js

@@ -29,6 +29,7 @@ const MAX_MODEL_FLAG_LEN = 32;
 const MAX_MODEL_VAL_LEN = 128;
 const MAX_PROMPTFLAG_LEN = 32;
 const MAX_PROMPT_LEN = 8192;   // 8 KB
+const MAX_PANELURL_LEN = 512;  // stesso cap di validBaseUrl (managed.js)
 // Nomi di server MCP dichiarabili per cella. Il tetto e' generoso rispetto agli
 // otto configurati qui, e la forma e' quella di un identificatore perche' il
 // nome finisce in un prefisso di tool passato al client.
@@ -75,6 +76,28 @@ function isSingleArgv(s) {
   return true;
 }
 
+// panelUrl: endpoint HTTP(S) di un pannello associato a una cella o a un
+// engine (es. il pannello web di un desktop container). Fail-closed e
+// STRICT, come il resto del modulo: solo http/https, e solo host loopback
+// (127.0.0.1, localhost, ::1) — un URL libero in fleet.json e' una superficie
+// che non serve a questo caso d'uso (il pannello vive sulla stessa macchina).
+// Validatore UNICO condiviso da parseEngine e parseCell: un valore "valido"
+// e' deciso in un solo posto, mai ricalcolato due volte con criteri diversi.
+// Esportato: il proxy del pannello disattiva la verifica TLS SOLO verso queste
+// destinazioni, e deve leggere la stessa lista che le autorizza — non una copia.
+const PANELURL_LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+function validPanelUrl(value) {
+  if (typeof value !== 'string' || !value || value.length > MAX_PANELURL_LEN) return false;
+  if (/[\x00-\x1f\x7f]|\s/.test(value)) return false; // no control char, no whitespace
+  let parsed;
+  try { parsed = new URL(value); } catch (_) { return false; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  // new URL() racchiude un host IPv6 fra parentesi quadre (es. "[::1]"): il
+  // confronto e' contro quella stessa forma, non contro "::1" nudo.
+  if (!PANELURL_LOOPBACK_HOSTS.has(parsed.hostname)) return false;
+  return true;
+}
+
 function validTmuxName(name) {
   return typeof name === 'string'
     && name.length <= MAX_TMUXSESSION_LEN
@@ -202,6 +225,15 @@ function parseDefinitions(raw, { allowLegacyTmuxNames = true } = {}) {
     // dichiarato qui, e leggerli dopo lo farebbe rifiutare per un dato che in
     // realta' c'e'. `models` e' opzionale: una configurazione che non lo ha
     // resta valida esattamente com'era.
+    //
+    // D2 (audit pacchetto): extraModels porta il DESCRITTORE completo (id,
+    // engine, contextWindow, maxTokens, reasoning), non solo l'id. Prima era
+    // Map<engine, Set<id>>: bastava per il gate "questo id e' ammesso?"
+    // (declaredFor), ma contextWindow/maxTokens/reasoning sparivano — e
+    // customCatalogFor/writePiProviderExtension, che ne hanno bisogno per
+    // emettere il catalogo, non li vedevano mai. Ora Map<engine, Map<id,
+    // model>>: chi ha bisogno solo degli id li ricava dalle CHIAVI della Map
+    // interna (stesso .has(id) di un Set — nessun consumatore esistente cambia).
     const models = [];
     const extraModels = new Map();
     if (d.models !== undefined) {
@@ -213,8 +245,8 @@ function parseDefinitions(raw, { allowLegacyTmuxNames = true } = {}) {
         const key = `${model.engine}::${model.id}`;
         if (seen.has(key)) return null;   // stesso id due volte per lo stesso profilo
         seen.add(key);
-        if (!extraModels.has(model.engine)) extraModels.set(model.engine, new Set());
-        extraModels.get(model.engine).add(model.id);
+        if (!extraModels.has(model.engine)) extraModels.set(model.engine, new Map());
+        extraModels.get(model.engine).set(model.id, model);
         models.push(model);
       }
     }
@@ -296,7 +328,20 @@ function parseEngine(e, { extraModels = null } = {}) {
     for (const key of ['command', 'args', 'env', 'promptMode', 'promptFlag', 'model']) {
       if (e[key] !== undefined) return null;
     }
-    return { id: e.id, label, rc, managed };
+    // panelUrl (opzionale): STESSO validatore e STESSA conservazione del ramo
+    // custom, qui sotto. Un engine managed puo' legittimamente avere un
+    // pannello, e il fallback engine->cella di cellStatus vale per entrambi.
+    // Prima di questo blocco il campo veniva scartato in silenzio: un valore
+    // valido spariva e uno invalido veniva accettato (fail-open) — rilievo 1
+    // dell'audit D8.
+    let managedPanelUrl;
+    if (e.panelUrl !== undefined) {
+      if (!validPanelUrl(e.panelUrl)) return null;
+      managedPanelUrl = e.panelUrl;
+    }
+    const managedOut = { id: e.id, label, rc, managed };
+    if (managedPanelUrl !== undefined) managedOut.panelUrl = managedPanelUrl;
+    return managedOut;
   }
 
   // command (obbligatorio, stringa non vuota; il trust si verifica a parte)
@@ -351,9 +396,19 @@ function parseEngine(e, { extraModels = null } = {}) {
   }
   // promptMode!=='flag' con promptFlag presente -> ignorato (campo non rilevante)
 
+  // panelUrl (opzionale): valore precompilato dall'engine (es. il pannello di
+  // un desktop container) — una cella puo' sovrascriverlo col proprio, vedi
+  // parseCell. Stessa validazione condivisa (validPanelUrl).
+  let panelUrl;
+  if (e.panelUrl !== undefined) {
+    if (!validPanelUrl(e.panelUrl)) return null;
+    panelUrl = e.panelUrl;
+  }
+
   const out = { id: e.id, label, rc, command: e.command, args, env, promptMode };
   if (model) out.model = model;
   if (promptFlag !== undefined) out.promptFlag = promptFlag;
+  if (panelUrl !== undefined) out.panelUrl = panelUrl;
   return out;
 }
 
@@ -472,6 +527,18 @@ function parseCell(c, engineIds, engineMap = new Map(), { allowLegacyTmuxNames =
     prompt = c.prompt;
   }
 
+  // panelUrl (opzionale, per-cella): endpoint HTTP(S) di un pannello associato
+  // alla cella (es. desktop container), sovrascrive quello precompilato
+  // dall'engine (vedi parseEngine). Opt-in: assente -> comportamento
+  // identico a oggi. Un valore PRESENTE ma malformato fa fallire l'INTERA
+  // definizione (return null): non collassa in "assente", sono due esiti
+  // opposti che si assomigliano.
+  let panelUrl;
+  if (c.panelUrl !== undefined) {
+    if (!validPanelUrl(c.panelUrl)) return null;
+    panelUrl = c.panelUrl;
+  }
+
   // mcp (opzionale): QUALI strumenti MCP ha questa cella, per NOME.
   //
   // Solo nomi, mai definizioni. Le definizioni vivono in un posto solo — la
@@ -557,6 +624,7 @@ function parseCell(c, engineIds, engineMap = new Map(), { allowLegacyTmuxNames =
   if (permissionPolicies) out.permissionPolicies = permissionPolicies;
   if (commands && Object.keys(commands).length) out.commands = commands;
   if (prompt !== undefined) out.prompt = prompt;
+  if (panelUrl !== undefined) out.panelUrl = panelUrl;
   if (mcp !== undefined) out.mcp = mcp;
   if (label !== undefined) out.label = label;
   if (legacyTmuxSession) {
@@ -596,7 +664,7 @@ function validateCommandTrust(command) {
 // lib/tmux/lifecycle.js: realpath su entrambi (symlink dentro home che punta
 // fuori -> rifiutato) e deve essere una directory.
 // ---------------------------------------------------------------------------
-function resolveCwd(cwd, home) {
+function resolveCwd(cwd, home, out) {
   try {
     const h = home || process.env.HOME;
     if (typeof cwd !== 'string' || !cwd || typeof h !== 'string' || !h) return null;
@@ -606,7 +674,18 @@ function resolveCwd(cwd, home) {
     if (!fs.statSync(real).isDirectory()) return null;
     if (real !== realHome && !real.startsWith(realHome + path.sep)) return null;
     return real;
-  } catch (_) { return null; }
+  } catch (e) {
+    // ENOENT = la cwd (o la home) non esiste (legittimo "non c'e'" -> null ->
+    // resolveCellCwd riporta 'invalid-cwd'/'home-unavailable'); altro code
+    // (EACCES/ELOOP/ENOTDIR...) = "esiste ma non ho potuto verificarla", e va
+    // distinto dal "non esiste sotto la home" che il messaggio altrimenti direbbe.
+    // Il verdetto (null -> cwd rifiutata, fail-closed di sicurezza) e' invariato;
+    // out.unverifiable porta il "perche'" a chi costruisce il messaggio
+    // (unportableCwdError). Il discriminante e' CHI ha fallito, non che ci sia
+    // stata un'eccezione.
+    if (out && e.code !== 'ENOENT') out.unverifiable = e.code || e.constructor.name;
+    return null;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -659,10 +738,22 @@ function deriveCwdRel(absCwd, home) {
 // loadDefinitions(p) -> parsed | null
 // Legge il file rifiutando i symlink; parse strict. Mai throw.
 // ---------------------------------------------------------------------------
-function loadDefinitions(p) {
+function loadDefinitions(p, out) {
   try {
     let st;
-    try { st = fs.lstatSync(p); } catch (_) { return null; } // missing -> null
+    try {
+      st = fs.lstatSync(p);
+    } catch (e) {
+      // ENOENT = il file non c'e' (legittimo "missing" -> null); qualsiasi altro
+      // code (EACCES/ELOOP/ENOTDIR...) = "esiste ma non ho potuto guardarlo", e va
+      // distinto dal "missing" che il caller altrimenti riporterebbe come "fleet
+      // unavailable" senza dire perche'. Il verdetto (null -> fail-closed) e'
+      // invariato; out.lstatBlocked porta il "perche'" a chi costruisce il
+      // messaggio. Il discriminante e' CHI ha fallito, non che ci sia stata
+      // un'eccezione.
+      if (out && e.code !== 'ENOENT') out.lstatBlocked = e.code || e.constructor.name;
+      return null;
+    }
     if (st.isSymbolicLink()) return null;                    // no symlink
     if (!st.isFile()) return null;
     const raw = fs.readFileSync(p, 'utf8');
@@ -726,11 +817,13 @@ const CAPS = {
   MAX_ENV_KEYS, MAX_ENV_KEY_LEN, MAX_ENV_VAL_LEN, MAX_LABEL_LEN,
   MAX_COMMAND_LEN, MAX_CWD_LEN, MAX_MODEL_FLAG_LEN, MAX_MODEL_VAL_LEN,
   MAX_PROMPTFLAG_LEN, MAX_PROMPT_LEN, MAX_CELL_COMMAND_LEN, MAX_TMUXSESSION_LEN,
+  MAX_PANELURL_LEN,
 };
 
 module.exports = {
   parseDefinitions,
   validateCommandTrust,
+  validPanelUrl, PANELURL_LOOPBACK_HOSTS,
   resolveCwd,
   normalizeCwdRel,
   deriveCwdRel,
@@ -744,4 +837,5 @@ module.exports = {
   // Costanti esposte anche piatte (comode per la UI/schema e i test)
   SCHEMA_VERSION, MAX_ENGINES, MAX_CELLS, MAX_ARGS, MAX_ARG_LEN,
   MAX_ENV_KEYS, MAX_ENV_KEY_LEN, MAX_ENV_VAL_LEN, MAX_PROMPT_LEN, MAX_CELL_COMMAND_LEN,
+  MAX_PANELURL_LEN,
 };

package/lib/fleet/launch-broker.js

@@ -48,6 +48,19 @@ function ensureRuntimeDir(dir) {
   }
 }
 
+// Nome leggibile del tipo di un fs.Stats, per un messaggio d'errore che
+// dice COSA ha trovato al posto di un socket (file regolare, directory,
+// symlink, ...) invece di limitarsi a "non e' un socket".
+function describeStatType(stat) {
+  if (stat.isSymbolicLink()) return 'un symlink';
+  if (stat.isDirectory()) return 'una directory';
+  if (stat.isFile()) return 'un file regolare';
+  if (stat.isFIFO()) return 'una FIFO';
+  if (stat.isCharacterDevice()) return 'un character device';
+  if (stat.isBlockDevice()) return 'un block device';
+  return 'un oggetto di tipo sconosciuto';
+}
+
 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');
@@ -63,6 +76,12 @@ function createLaunchBroker(cfg = {}) {
   let closed = false;
   const pending = new Map();
   const ttlMs = Math.max(1000, Number(cfg.launchTokenTtlMs) || 15000);
+  // R3.1.1 (opt-in): se cfg.onLease e' registrato e il payload porta `lease`, la
+  // connessione accettata col nonce one-shot resta APERTA dopo il frame payload e
+  // viene consegnata a onLease(socket, lease) per divenire il canale lease. Senza
+  // onLease o senza lease il comportamento e' invariato (socket.end, one-shot):
+  // le celle non-ospite non sono toccate.
+  const onLease = typeof cfg.onLease === 'function' ? cfg.onLease : null;
 
   function expire(nonce) {
     const entry = pending.get(nonce);
@@ -84,6 +103,11 @@ function createLaunchBroker(cfg = {}) {
         let raw = '';
         socket.setEncoding('utf8');
         socket.setTimeout(3000, () => socket.destroy());
+        // Correzione (audit 2a, stesso buco trovato in cell-lease-server.js):
+        // il broker scrive su questo socket (il payload, o dopo F-B onLease
+        // prima). Un peer che muore mentre quella write e' in volo emette
+        // 'error' senza listener -> throw fatale, INTERO processo giu'.
+        socket.once('error', () => { try { socket.destroy(); } catch (_) {} });
         socket.on('data', (chunk) => {
           raw += chunk;
           if (raw.length > REQUEST_LIMIT) return socket.destroy();
@@ -97,14 +121,102 @@ function createLaunchBroker(cfg = {}) {
           // 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(); }
+          if (entry.lease && onLease) {
+            // R3.1.1: la stessa connessione resta APERTA dopo il frame payload.
+            // Disarmiamo il timeout one-shot e rimuoviamo il data handler del nonce:
+            // la socket arriva pulita a onLease, che la dedica al canale lease. Cosi'
+            // un refresh successivo non riparla sul nonce esaurito (il reparse della
+            // riga nonce, con pending vuota, distruggeva la connessione) e non scatta
+            // piu' il timeout idle da 3s pensato per il one-shot.
+            socket.setTimeout(0);
+            socket.removeAllListeners('data');
+            // F-B (audit 2a @ 142e272): la lease PRIMA del payload. onLease
+            // associa la connessione al lease manager (attachInitial); solo se
+            // committa il payload viene scritto. Se onLease ritorna false, o ha
+            // gia' distrutto la socket, il payload NON parte: il client riceve
+            // la chiusura prima del frame, receivePayload rigetta ('launch
+            // broker closed early') e il child NON NASCE con una lease che il
+            // server non ha mai committato. Prima il payload era scritto prima
+            // di onLease: la cella partiva anche con attach fallito (20/20 sonda).
+            const denied = onLease(socket, entry.lease) === false || socket.destroyed;
+            if (denied) return;
+            try { socket.write(entry.encoded); } catch (_) { socket.destroy(); return; }
+          } else {
+            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 (_) {}
+        // Stesso rigore gia' applicato alla directory in ensureRuntimeDir
+        // (chmod, poi VERIFICA il risultato reale, fallisci chiuso se non
+        // conforme): la dir 0700 basta da sola a impedire l'attraversamento
+        // del path a qualunque altro utente, indipendentemente dal mode del
+        // socket — verificato (attraversare una directory richiede il bit x
+        // su OGNI componente del path, il mode del file terminale non conta
+        // per chi non puo' nemmeno raggiungerlo). Ma questo file non tratta
+        // quella garanzia come l'unica: se domani ensureRuntimeDir avesse un
+        // buco, o il filesystem sottostante non applicasse i permessi POSIX
+        // come atteso, il mode del socket e' l'unica barriera indipendente
+        // rimasta.
+        //
+        // Riconsegna: la prima versione di questa guardia verificava SOLO il
+        // mode (chmod, poi statSync().mode) — il PERMESSO, non l'IDENTITA'.
+        // Misurato: sostituendo il path con un FILE REGOLARE mode 0600
+        // subito dopo il chmod (stesso trust boundary: serve comunque
+        // accesso alla dir 0700), issue() si risolveva lo stesso — la
+        // guardia non si accorgeva che l'oggetto non era piu' un socket.
+        // Ora: lstatSync (non statSync, come la dir sopra — un socket non
+        // va MAI seguito attraverso un symlink) sia prima sia dopo il
+        // chmod, isSocket() verificato in entrambi i momenti, e
+        // dev/ino confrontati fra i due lstatSync per rilevare una
+        // sostituzione avvenuta DURANTE l'intervallo del chmod stesso.
+        //
+        // LIMITE DICHIARATO, non nascosto: questo chiude la finestra fra il
+        // PRIMO lstatSync (il piu' presto possibile dopo il bind) e il
+        // SECONDO (dopo il chmod) — non la finestra fra il bind stesso e il
+        // primo lstatSync (Node non espone un modo per fstat l'fd del
+        // server UDS appena bindato prima di riosservarlo per path), ne'
+        // quella fra questa verifica e il momento in cui un client si
+        // connette davvero. Chiuderle richiederebbe verificare l'identita'
+        // a OGNI connessione accettata (fstat sul socket accettato via fd,
+        // non per path) — fuori scope qui: chi ha accesso alla dir 0700 ha
+        // gia' lo stesso UID di questo processo, e a quel punto puo' fare
+        // molto altro (killare il processo, ptrace) che nessun chmod
+        // fermerebbe — non e' un'escalation di privilegi nuova, e' il
+        // limite intrinseco del modello "stesso utente = stesso trust
+        // boundary" gia' assunto da questo file per la directory.
+        let mode = null;
+        try {
+          const pre = fs.lstatSync(socketPath);
+          if (!pre.isSocket()) {
+            throw new Error(`atteso un socket, trovato ${describeStatType(pre)}`);
+          }
+          fs.chmodSync(socketPath, 0o600);
+          const post = fs.lstatSync(socketPath);
+          if (!post.isSocket()) {
+            throw new Error(`non e' piu' un socket dopo il chmod: ${describeStatType(post)}`);
+          }
+          if (post.dev !== pre.dev || post.ino !== pre.ino) {
+            throw new Error("il file al path del socket e' stato sostituito durante la verifica (dev/ino cambiati fra i due lstatSync)");
+          }
+          mode = post.mode & 0o777;
+        } catch (error) {
+          try { server.close(); } catch (_) {}
+          try { fs.unlinkSync(socketPath); } catch (_) {}
+          server = null; starting = null;
+          reject(new Error(`unsafe launch broker socket: ${error.message}`));
+          return;
+        }
+        if (mode !== 0o600) {
+          try { server.close(); } catch (_) {}
+          try { fs.unlinkSync(socketPath); } catch (_) {}
+          server = null; starting = null;
+          reject(new Error(`unsafe launch broker socket: mode ${mode.toString(8)} dopo chmod, atteso 0600`));
+          return;
+        }
         server.unref(); starting = null; resolve(socketPath);
       });
     });
@@ -114,7 +226,7 @@ function createLaunchBroker(cfg = {}) {
   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 };
+    const entry = { encoded: encodePayload(payload), expires: Date.now() + ttlMs, timer: null, lease: payload && payload.lease ? payload.lease : null };
     entry.timer = setTimeout(() => expire(nonce), ttlMs);
     entry.timer.unref?.();
     pending.set(nonce, entry);

package/lib/fleet/lease-client.js

@@ -0,0 +1,191 @@
+'use strict';
+
+// Lease-client lato SUPERVISORE (cell-exec.js).
+//
+// Mantiene la connessione lease iniziale (la stessa del broker one-shot che resta
+// APERTA dopo il payload, R3.1.1), invia refresh a cadenza 20s (R3.2 heartbeat),
+// e su EOF reconnecta all'endpoint stabile (R3.3.2).
+//
+// Fetta 2b (contratto rev1, A2/B1): l'autenticazione del reconnect e' un proof
+// HMAC firmato dal server col verifier per-installazione — la capability statica
+// della 2a e' revocata. Il proof NON arriva nel payload: il server lo consegna
+// sul canale (frame lease all'attach, ack a ogni refresh) e il supervisore lo
+// detiene in memoria, presentandolo tale e quale al reconnect. R3.1.2 invariato:
+// niente di tutto questo transita mai nell'env del child.
+//
+// Side effect isolati e iniettabili (seams) per testabilita', come altrove.
+
+const net = require('node:net');
+const L = require('./cell-lease.js');
+
+function startLeaseClient(initialSocket, info, seams = {}) {
+  if (!initialSocket || !info || !info.stablePath || !info.launchEpoch) return null;
+  const setTimer = seams.setTimeout || ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = seams.clearTimeout || ((t) => { if (t) clearTimeout(t); });
+  const netImpl = seams.net || net;
+  const now = seams.now || Date.now;
+
+  let stopped = false;
+  let current = initialSocket;
+  let refreshTimer = null;
+  let reconnectTimer = null;
+  // 2b: ultimo proof consegnato dal server sul canale (attach/refresh). Vive
+  // SOLO in memoria qui: e' effimero per costruzione (B8), non si persiste.
+  let heldProof = null;
+  // R3.2: bound di grace per i reconnect (eofAt + GRACE_MS). Oltre non si ritenta.
+  let reconnectDeadline = null;
+
+  function send(obj) {
+    if (!current || current.destroyed || !current.writable) return false;
+    try { current.write(`${JSON.stringify(obj)}\n`); return true; } catch (_) { return false; }
+  }
+
+  function armRefresh() {
+    clearTimer(refreshTimer);
+    refreshTimer = setTimer(() => {
+      if (stopped) return;
+      send({ type: 'refresh' });
+      armRefresh();
+    }, L.REFRESH_MS);
+    if (refreshTimer && typeof refreshTimer.unref === 'function') refreshTimer.unref();
+  }
+
+  function onEOF() {
+    if (stopped) return;
+    if (current) { try { current.removeAllListeners('data'); current.removeAllListeners('close'); current.removeAllListeners('end'); } catch (_) {} }
+    current = null;
+    clearTimer(refreshTimer);
+    // R3.2: la grace parte dall'EOF lato supervisore. I reconnect sono bounded da
+    // eofAt + GRACE_MS: rev13 S3.3 garantisce >=2 tentativi STRETTAMENTE dentro.
+    reconnectDeadline = now() + L.GRACE_MS;
+    armReconnect(0); // primo tentativo subito, poi a cadenza RECONNECT_CADENCE_MS
+  }
+
+  let lostNotified = false;
+
+  function armReconnect(delay) {
+    clearTimer(reconnectTimer);
+    // R3.2: oltre la grace non si ritenta (deny o server muto non vanno in loop).
+    if (reconnectDeadline != null && now() >= reconnectDeadline) {
+      // F-B (audit 2a @ 142e272): la grace e' scaduta senza un reconnect
+      // riuscito: la lease e' PERSA per questo supervisore. Prima si desisteva
+      // in silenzio e il child restava un orfano senza lease per tutta la sua
+      // vita, senza che nessuno lo sapesse. Ora il supervisore viene avvisato
+      // (info.onLost, una volta sola): cell-exec ferma il child e muore con lui.
+      if (!lostNotified) {
+        lostNotified = true;
+        if (typeof info.onLost === 'function') { try { info.onLost(); } catch (_) {} }
+      }
+      return;
+    }
+    reconnectTimer = setTimer(() => {
+      if (stopped) return;
+      attemptReconnect();
+    }, delay);
+    if (reconnectTimer && typeof reconnectTimer.unref === 'function') reconnectTimer.unref();
+  }
+
+  function attemptReconnect() {
+    let settled = false;
+    // R3.3.4: generation puo' essere un getter (cell-exec la fa avanzare coi restart)
+    // o un valore; al reconnect presentiamo sempre quella corrente.
+    const curGeneration = typeof info.generation === 'function' ? info.generation() : (info.generation || 0);
+    const sock = netImpl.createConnection(info.stablePath, () => {
+      // 2b: presentiamo il proof detenuto. Senza proof (nessun ack ricevuto, o
+      // persistenza fallita lato server) il messaggio parte comunque senza: il
+      // server nega — e il tentativo resta bounded dalla grace, come in 2a.
+      const msg = { type: 'reconnect', generation: curGeneration, ...(heldProof ? { proof: heldProof } : {}) };
+      try { sock.write(`${JSON.stringify(msg)}\n`); } catch (_) { try { sock.destroy(); } catch (e) {} }
+    });
+    // R3.2: per-attempt timeout. Se il server accetta la connessione ma non risponde
+    // (socket appesa) forziamo la chiusura e ritentiamo: senza questo il client
+    // restava con 1 solo tentativo e 0 timer successivi. Cadence come upper bound.
+    const attemptTimer = setTimer(() => {
+      if (settled) return;
+      settled = true;
+      try { sock.destroy(); } catch (_) {}
+      armReconnect(0);
+    }, L.RECONNECT_CADENCE_MS);
+    if (attemptTimer && typeof attemptTimer.unref === 'function') attemptTimer.unref();
+    let buf = '';
+    sock.setEncoding('utf8');
+    sock.on('data', (chunk) => {
+      buf += chunk;
+      const nl = buf.indexOf('\n');
+      if (nl === -1) return;
+      const line = buf.slice(0, nl); buf = buf.slice(nl + 1);
+      let msg; try { msg = JSON.parse(line); } catch (_) { return; }
+      if (settled) return;
+      if (msg.type === 'lease') {
+        settled = true;
+        clearTimer(attemptTimer);
+        // R3.3.4: reconnect riuscito, lease nuovo. Il proof consegnato col lease
+        // nuovo diventa quello detenuto; riprende il refresh loop.
+        clearTimer(reconnectTimer);
+        if (msg.proof && typeof msg.proof === 'object') heldProof = msg.proof;
+        current = sock;
+        bindLive(sock);
+        armRefresh();
+      } else if (msg.type === 'deny') {
+        settled = true;
+        clearTimer(attemptTimer);
+        // R3.3.5: rifiutato (proof rifiutato, oltre grace o identity). Riprova a
+        // cadenza: rev13 S3.3 garantisce >=2 tentativi strettamente dentro la grace.
+        try { sock.destroy(); } catch (_) {}
+        armReconnect(L.RECONNECT_CADENCE_MS);
+      }
+    });
+    sock.once('close', () => {
+      if (settled) return;
+      settled = true;
+      clearTimer(attemptTimer);
+      armReconnect(L.RECONNECT_CADENCE_MS);
+    });
+    sock.once('error', () => { try { sock.destroy(); } catch (_) {} });
+  }
+
+  // 2b: il canale live legge cio' che il server consegna — ack col proof a ogni
+  // refresh, frame lease (col proof) all'attach. Senza lettura il proof non
+  // arriverebbe mai al detentore.
+  function bindLive(sock) {
+    sock.removeAllListeners('close');
+    sock.removeAllListeners('end');
+    let buf = '';
+    sock.on('data', (chunk) => {
+      buf += chunk;
+      let nl;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl); buf = buf.slice(nl + 1);
+        let msg; try { msg = JSON.parse(line); } catch (_) { continue; }
+        if ((msg.type === 'ack' || msg.type === 'lease') && msg.proof && typeof msg.proof === 'object') {
+          heldProof = msg.proof;
+        }
+      }
+    });
+    sock.once('close', onEOF);
+    sock.once('end', onEOF);
+    // Il peer puo' morire senza leggere (RST: ECONNRESET su write/read): un
+    // 'error' senza listener e' fatale per il processo supervisore. Assorbilo e
+    // lascia che la 'close' che segue armi la grace, stessa forma del server.
+    sock.once('error', () => { try { sock.destroy(); } catch (_) {} });
+  }
+
+  // Avvio: la connessione iniziale (broker) e' gia' aperta. Arma refresh + EOF.
+  bindLive(current);
+  armRefresh();
+  send({ type: 'refresh' }); // primo refresh immediato
+
+  return {
+    stop() {
+      stopped = true;
+      clearTimer(refreshTimer);
+      clearTimer(reconnectTimer);
+      try { current && current.destroy(); } catch (_) {}
+      current = null;
+    },
+    _isConnected: () => !!current && !current.destroyed,
+    _heldProof: () => heldProof,
+  };
+}
+
+module.exports = { startLeaseClient };