@mmmbuto/nexuscrew 0.9.2 → 0.9.4

package/lib/fleet/builtin.js

@@ -30,7 +30,8 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const {
-  loadDefinitions, atomicWrite, CAPS, MAX_CELLS, validTmuxName,
+  loadDefinitions, atomicWrite, CAPS, MAX_CELLS, validTmuxName, validateCommandTrust,
+  aggiornaDefinizioni,
   cellIdFromTmuxSession,
   resolveCwd, normalizeCwdRel, deriveCwdRel,
 } = require('./definitions.js');
@@ -87,13 +88,20 @@ function draftFrom(defs) {
 // ricevono l'engine standard Shell senza riscrivere celle o sostituire un id
 // scelto dall'utente. Se lo store e' pieno o la scrittura non e' possibile, il
 // bootstrap resta utilizzabile con le definizioni precedenti.
-function backfillShellEngine(defsPath, defs) {
-  if (!defs || defs.engines.some((engine) => engine.managed?.client === 'shell')) return defs;
-  if (defs.engines.some((engine) => engine.id === 'shell.local')) return defs;
-  if (defs.engines.length >= CAPS.MAX_ENGINES) return defs;
-  const draft = draftFrom(defs);
-  draft.engines.push(defaultShellEngine());
-  try { return atomicWrite(defsPath, draft); } catch (_) { return defs; }
+function backfillShellEngine(defsPath, defs, log) {
+  if (!defs) return defs;
+  // Le condizioni si valutano su cio' che si legge DENTRO il lock, non
+  // sullo stato che avevamo in mano: e' la differenza fra decidere sul
+  // presente e decidere su una fotografia.
+  const esito = aggiornaDefinizioni(defsPath, (dentro) => {
+    if (dentro.engines.some((engine) => engine.managed?.client === 'shell')) return null;
+    if (dentro.engines.some((engine) => engine.id === 'shell.local')) return null;
+    if (dentro.engines.length >= CAPS.MAX_ENGINES) return null;
+    const draft = draftFrom(dentro);
+    draft.engines.push(defaultShellEngine());
+    return draft;
+  }, { log });
+  return esito || defs;
 }
 
 // Backfill platform-aware dell'engine Agy primario (design §4.2): installazioni
@@ -111,12 +119,17 @@ function backfillAgyEngine(defsPath, defs, cfg = {}) {
   const termux = platform === 'android'
     || termuxRuntimePaths(cfg.env || process.env, { platform, home: cfg.home }) !== null;
   if (termux || (platform !== 'linux' && platform !== 'darwin')) return defs;
-  if (defs.engines.some((engine) => engine.managed?.client === 'agy')) return defs;
-  if (defs.engines.some((engine) => engine.id === 'agy.native')) return defs;
-  if (defs.engines.length >= CAPS.MAX_ENGINES) return defs;
-  const draft = draftFrom(defs);
-  draft.engines.push(defaultAgyEngine());
-  try { return atomicWrite(defsPath, draft); } catch (_) { return defs; }
+  // Il gate di piattaforma non dipende dallo store e resta fuori dal lock:
+  // non si tiene un lock per rispondere a una domanda sul sistema.
+  const esito = aggiornaDefinizioni(defsPath, (dentro) => {
+    if (dentro.engines.some((engine) => engine.managed?.client === 'agy')) return null;
+    if (dentro.engines.some((engine) => engine.id === 'agy.native')) return null;
+    if (dentro.engines.length >= CAPS.MAX_ENGINES) return null;
+    const draft = draftFrom(dentro);
+    draft.engines.push(defaultAgyEngine());
+    return draft;
+  }, { log: cfg.log });
+  return esito || defs;
 }
 
 // Engine desktop.local: NON managed (nessun client/provider AI, solo command+args
@@ -137,15 +150,47 @@ function backfillAgyEngine(defsPath, defs, cfg = {}) {
 function risolviEseguibile(nome) {
   const dirs = String(process.env.PATH || '').split(path.delimiter).filter(Boolean);
   for (const dir of dirs) {
-    try {
-      const reale = fs.realpathSync(path.join(dir, nome));
-      const st = fs.statSync(reale);
-      if (st.isFile() && (st.mode & 0o100)) return reale;
-    } catch (_) { /* voce del PATH inservibile: si prova la prossima */ }
+    let reale;
+    try { reale = fs.realpathSync(path.join(dir, nome)); } catch (_) { continue; }
+    // La decisione la prende la STESSA funzione che deciderà al salvataggio.
+    // Riscriverne una copia qui significava poter divergere, ed era divergente:
+    // un `docker` 0777 passava il controllo locale (file + eseguibile) e veniva
+    // poi rifiutato come world-writable — cioè il default proposto non superava
+    // la validazione che lo attendeva.
+    if (!validateCommandTrust(reale).ok) continue;
+    // In più, una condizione che la validazione NON esprime: un binario
+    // ineccepibile dentro una directory scrivibile da chiunque è sostituibile
+    // da chiunque. Il salvataggio lo accetterebbe; noi non lo PROPONIAMO —
+    // scegliere il default è nostro, e su una scelta nostra si può essere più
+    // prudenti del minimo richiesto.
+    if (dirScrivibileDaTutti(reale)) continue;
+    return reale;
   }
   return null;
 }
 
+// Guarda la directory che CONTIENE l'eseguibile, non l'eseguibile: è lì che si
+// decide chi può sostituirlo. Sticky bit escluso (come /tmp: lì il rename
+// altrui è già impedito dal kernel).
+function dirScrivibileDaTutti(file) {
+  // Tutta la CATENA, non il solo genitore: con `/a` scrivibile da chiunque,
+  // `/a/b/docker` resta sostituibile rinominando `b` — il binario e la sua
+  // directory immediata possono essere ineccepibili e il percorso no. Un audit
+  // ha riprodotto esattamente questo caso su un controllo fermo al genitore.
+  //
+  // Lo sticky bit interrompe la risalita per quel livello: li' il kernel
+  // impedisce gia' di rinominare o rimuovere roba altrui (e' il caso di /tmp).
+  let dir = path.dirname(file);
+  for (;;) {
+    let st;
+    try { st = fs.statSync(dir); } catch (_) { return true; } // non ispezionabile: scarta
+    if ((st.mode & 0o002) && !(st.mode & 0o1000)) return true;
+    const su = path.dirname(dir);
+    if (su === dir) return false; // radice raggiunta: catena pulita
+    dir = su;
+  }
+}
+
 // Il command DEVE essere un path assoluto: `validateCommandTrust` e' la trust
 // boundary degli engine, e un nome relativo si risolverebbe via PATH — cioe'
 // via qualcosa che l'ambiente puo' cambiare sotto di noi. Dichiarare 'docker'
@@ -191,16 +236,28 @@ function defaultDesktopEngine() {
 // bootstrap: una dipendenza nuova sul percorso di avvio per una comodita'.
 // Resta MANUALE: chi ha il container se lo aggiunge nella propria procedura
 // — e' il posto dove qualcuno sa gia' che il container esiste.
-function backfillDesktopEngine(defsPath, defs) {
+function backfillDesktopEngine(defsPath, defs, log) {
   if (!defs) return defs;
-  const esistente = defs.engines.find((engine) => engine.id === 'desktop.local');
-  if (esistente) return riparaDesktopEngine(defsPath, defs, esistente);
-  if (defs.engines.length >= CAPS.MAX_ENGINES) return defs;
-  const draft = draftFrom(defs);
-  draft.engines.push(defaultDesktopEngine());
-  try { return atomicWrite(defsPath, draft); } catch (_) { return defs; }
+  if (defs.engines.some((engine) => engine.id === 'desktop.local')) {
+    return riparaDesktopEngine(defsPath, defs, log);
+  }
+  const esito = aggiornaDefinizioni(defsPath, (dentro) => {
+    if (dentro.engines.some((engine) => engine.id === 'desktop.local')) return null;
+    if (dentro.engines.length >= CAPS.MAX_ENGINES) return null;
+    const draft = draftFrom(dentro);
+    draft.engines.push(defaultDesktopEngine());
+    return draft;
+  }, { log });
+  return esito || defs;
 }
 
+// A DIFFERENZA del backfill qui sopra, questa e' agganciata al bootstrap, e
+// non contraddice la decisione del 2026-08-14: non AGGIUNGE l'engine a chi non
+// ce l'ha e non presuppone alcun container: tocca soltanto un `desktop.local`
+// gia' presente, il cui comando e' rotto per costruzione. Senza quell'aggancio
+// la funzione non aveva chiamanti — scritta, testata e mai eseguita, con un
+// test verde perche' la invocava direttamente.
+//
 // Le installazioni che hanno gia' ricevuto il backfill portano in
 // configurazione un `command` RELATIVO, che la trust boundary rifiuta: per
 // loro l'aggiornamento del default non cambia nulla, perche' il backfill salta
@@ -210,17 +267,51 @@ function backfillDesktopEngine(defsPath, defs) {
 // Prudente per costruzione: interviene SOLO se il comando non e' assoluto e si
 // chiama ancora `docker`. Un path assoluto — o un comando che l'utente ha
 // cambiato in altro — non viene toccato: quella e' una scelta, non un residuo.
-function riparaDesktopEngine(defsPath, defs, esistente) {
-  const cmd = typeof esistente.command === 'string' ? esistente.command : '';
-  if (!cmd || path.isAbsolute(cmd)) return defs;
-  if (path.basename(cmd) !== 'docker') return defs;
+function riparaDesktopEngine(defsPath, defs, log = () => {}) {
+  if (!defs || !Array.isArray(defs.engines)) return defs;
+  if (!eDaRiparare(defs)) return defs;          // scarto rapido, senza lock
   const risolto = risolviEseguibile('docker');
-  if (!risolto) return defs; // niente docker qui: meglio invariato che finto
-  const draft = draftFrom(defs);
-  const voce = draft.engines.find((engine) => engine.id === 'desktop.local');
-  if (!voce) return defs;
-  voce.command = risolto;
-  try { return atomicWrite(defsPath, draft); } catch (_) { return defs; }
+  if (!risolto) return defs;                    // niente docker fidato: invariato
+
+  // La condizione si rivaluta DENTRO il lock, sullo stato appena riletto: fra
+  // il nostro scarto rapido e la scrittura qualcuno puo' aver gia' corretto
+  // quella voce, o averla cambiata in altro. Rinunciare costa un altro avvio;
+  // sovrascrivere costa un dato.
+  const esito = aggiornaDefinizioni(defsPath, (dentro) => {
+    if (!eDaRiparare(dentro)) return null;
+    const draft = draftFrom(dentro);
+    const voce = draft.engines.find((engine) => engine.id === 'desktop.local');
+    if (!voce) return null;
+    voce.command = risolto;
+    return draft;
+  }, {
+    log: (m) => log(m),
+  });
+  if (!esito) {
+    log('desktop.local: riparazione del comando non persistita (definizioni non leggibili)');
+    return defs;
+  }
+  if (esito.engines.find((e) => e.id === 'desktop.local')?.command === 'docker') {
+    // Il lock c'era ma la scrittura non ha attecchito: dirlo, invece di
+    // lasciare l'avvio convinto di aver fatto il suo lavoro.
+    log('desktop.local: riparazione del comando non persistita');
+  }
+  return esito;
+}
+
+// La condizione di riparabilità, in un posto solo perché va valutata due volte:
+// sullo stato in mano e su quello riletto un istante prima di scrivere.
+//
+// `docker` NUDO, non un basename qualsiasi: `vendor/docker` è un percorso
+// relativo che qualcuno ha scritto apposta per il proprio binario, e
+// sostituirlo con il Docker di sistema è distruggere una scelta, non riparare
+// un residuo. Il residuo che stiamo correggendo è esattamente la stringa che il
+// nostro engine dichiarava.
+function eDaRiparare(defs) {
+  if (!defs || !Array.isArray(defs.engines)) return false;
+  const voce = defs.engines.find((engine) => engine.id === 'desktop.local');
+  if (!voce) return false;
+  return voce.command === 'docker';
 }
 
 // Backfill dell'engine Kimi Code CLI nativo: installazioni esistenti ricevono
@@ -229,13 +320,20 @@ function riparaDesktopEngine(defsPath, defs, esistente) {
 // shebang. Idempotente (gia' presente -> skip), NON sovrascrive un id
 // 'kimi.native' gia' scelto dall'utente per altro (collisione -> skip, store
 // invariato), rispetta il cap MAX_ENGINES. Non tocca CELLE.
-function backfillKimiEngine(defsPath, defs) {
-  if (!defs || defs.engines.some((engine) => engine.managed?.client === 'kimi')) return defs;
-  if (defs.engines.some((engine) => engine.id === 'kimi.native')) return defs;
-  if (defs.engines.length >= CAPS.MAX_ENGINES) return defs;
-  const draft = draftFrom(defs);
-  draft.engines.push(defaultKimiEngine());
-  try { return atomicWrite(defsPath, draft); } catch (_) { return defs; }
+function backfillKimiEngine(defsPath, defs, log) {
+  if (!defs) return defs;
+  // Le condizioni si valutano su cio' che si legge DENTRO il lock, non
+  // sullo stato che avevamo in mano: e' la differenza fra decidere sul
+  // presente e decidere su una fotografia.
+  const esito = aggiornaDefinizioni(defsPath, (dentro) => {
+    if (dentro.engines.some((engine) => engine.managed?.client === 'kimi')) return null;
+    if (dentro.engines.some((engine) => engine.id === 'kimi.native')) return null;
+    if (dentro.engines.length >= CAPS.MAX_ENGINES) return null;
+    const draft = draftFrom(dentro);
+    draft.engines.push(defaultKimiEngine());
+    return draft;
+  }, { log });
+  return esito || defs;
 }
 
 // Backfill platform-aware dell'engine Grok Build (grok.native): come Agy,
@@ -251,12 +349,17 @@ function backfillGrokEngine(defsPath, defs, cfg = {}) {
   const termux = platform === 'android'
     || termuxRuntimePaths(cfg.env || process.env, { platform, home: cfg.home }) !== null;
   if (termux || (platform !== 'linux' && platform !== 'darwin')) return defs;
-  if (defs.engines.some((engine) => engine.managed?.client === 'grok')) return defs;
-  if (defs.engines.some((engine) => engine.id === 'grok.native')) return defs;
-  if (defs.engines.length >= CAPS.MAX_ENGINES) return defs;
-  const draft = draftFrom(defs);
-  draft.engines.push(defaultGrokEngine());
-  try { return atomicWrite(defsPath, draft); } catch (_) { return defs; }
+  // Il gate di piattaforma non dipende dallo store e resta fuori dal lock:
+  // non si tiene un lock per rispondere a una domanda sul sistema.
+  const esito = aggiornaDefinizioni(defsPath, (dentro) => {
+    if (dentro.engines.some((engine) => engine.managed?.client === 'grok')) return null;
+    if (dentro.engines.some((engine) => engine.id === 'grok.native')) return null;
+    if (dentro.engines.length >= CAPS.MAX_ENGINES) return null;
+    const draft = draftFrom(dentro);
+    draft.engines.push(defaultGrokEngine());
+    return draft;
+  }, { log: cfg.log });
+  return esito || defs;
 }
 
 // Backfill dell'engine VL/Vivling (vl.native): come Kimi, NESSUN platform gate
@@ -264,13 +367,20 @@ function backfillGrokEngine(defsPath, defs, cfg = {}) {
 // -> skip), NON sovrascrive un id 'vl.native' gia' scelto dall'utente per altro
 // (collisione -> skip, store invariato), rispetta il cap MAX_ENGINES. Non tocca
 // CELLE.
-function backfillVlEngine(defsPath, defs) {
-  if (!defs || defs.engines.some((engine) => engine.managed?.client === 'vl')) return defs;
-  if (defs.engines.some((engine) => engine.id === 'vl.native')) return defs;
-  if (defs.engines.length >= CAPS.MAX_ENGINES) return defs;
-  const draft = draftFrom(defs);
-  draft.engines.push(defaultVlEngine());
-  try { return atomicWrite(defsPath, draft); } catch (_) { return defs; }
+function backfillVlEngine(defsPath, defs, log) {
+  if (!defs) return defs;
+  // Le condizioni si valutano su cio' che si legge DENTRO il lock, non
+  // sullo stato che avevamo in mano: e' la differenza fra decidere sul
+  // presente e decidere su una fotografia.
+  const esito = aggiornaDefinizioni(defsPath, (dentro) => {
+    if (dentro.engines.some((engine) => engine.managed?.client === 'vl')) return null;
+    if (dentro.engines.some((engine) => engine.id === 'vl.native')) return null;
+    if (dentro.engines.length >= CAPS.MAX_ENGINES) return null;
+    const draft = draftFrom(dentro);
+    draft.engines.push(defaultVlEngine());
+    return draft;
+  }, { log });
+  return esito || defs;
 }
 
 // Applica engine + modello + policy come un'unica transizione. Ogni engine ricorda
@@ -468,6 +578,16 @@ async function createBuiltinFleet(cfg = {}) {
     : off;
 
   if (!readonly()) {
+    // Audit 093, rilievo 3: lo snapshot della BASE si prende QUI, alla lettura
+    // che ha prodotto `boot` — non con una rilettura dopo la migrazione. Il
+    // vecchio `primaDelloScrivere` era una rilettura: una scrittura arrivata
+    // DURANTE migrateLegacyTmuxSessions (una catena di chiamate tmux: finestra
+    // larga) era già dentro la rilettura, il confronto passava e `boot`,
+    // costruito sullo stato pre-migrazione, cancellava il lavoro altrui. Con
+    // lo snapshot alla fonte, il confronto dentro il lock copre la finestra
+    // INTERA da questa lettura alla presa. `boot` e il futuro `dentro` sono
+    // entrambi normalizzati da loadDefinitions: il confronto resta coerente.
+    const baseAllaLettura = JSON.stringify(boot);
     // La migrazione precede QUALUNQUE backfill/scrittura: loadDefinitions normalizza
     // i nomi legacy solo in memoria. Se il rename e' ambiguo o fallisce, fleet.json
     // resta byte-invariato e la Fleet non puo creare una seconda sessione safe.
@@ -482,17 +602,36 @@ async function createBuiltinFleet(cfg = {}) {
       return blocked(`${detail} [${code}]`, code);
     }
     if (migration.needsPersistence) {
-      try { boot = atomicWrite(defsPath, boot); }
-      catch (_) {
+      // `boot` e' gia' stato mutato in memoria dalla migrazione: qui non si puo'
+      // ricostruire il draft dallo stato riletto, si puo' solo verificare che
+      // nessun altro abbia scritto nel frattempo — per TUTTA la finestra, da
+      // `baseAllaLettura` in poi (vedi il commento alla snapshot). Se qualcuno
+      // l'ha fatto si RINUNCIA: la migrazione e' idempotente e si riapplica al
+      // prossimo avvio, mentre sovrascrivere cancellerebbe il lavoro altrui.
+      let persistito = null;
+      try {
+        // `propaga` anche qui: senza, una rinuncia del lock tornava come stato
+        // valido e l'avvio proseguiva dichiarando implicitamente una migrazione
+        // che non era stata scritta.
+        persistito = aggiornaDefinizioni(defsPath, (dentro) => (
+          JSON.stringify(dentro) === baseAllaLettura ? boot : null
+        ), { propaga: true, log: cfg.log });
+      } catch (_) { persistito = null; }
+      if (!persistito) {
         return blocked('migrazione tmux completata ma fleet.json non e persistibile [TMUX_MIGRATION_PERSIST_FAILED]',
           'TMUX_MIGRATION_PERSIST_FAILED');
       }
+      boot = persistito;
     }
-    boot = backfillShellEngine(defsPath, boot);
+    boot = backfillShellEngine(defsPath, boot, cfg.log);
     boot = backfillAgyEngine(defsPath, boot, cfg);
-    boot = backfillKimiEngine(defsPath, boot);
+    boot = backfillKimiEngine(defsPath, boot, cfg.log);
     boot = backfillGrokEngine(defsPath, boot, cfg);
-    boot = backfillVlEngine(defsPath, boot);
+    boot = backfillVlEngine(defsPath, boot, cfg.log);
+    // Ripara (non aggiunge) un desktop.local gia' presente col comando relativo.
+    // Il logger va PASSATO: senza, il messaggio di fallimento si ferma a un
+    // callback che nessuno fornisce — cioe' il silenzio che si voleva togliere.
+    boot = riparaDesktopEngine(defsPath, boot, cfg.log);
   }
 
   // Adopt or create the shared server before exposing a mutable Fleet. Reapply
@@ -555,14 +694,28 @@ async function createBuiltinFleet(cfg = {}) {
   // Scrive il draft mutato; atomicWrite valida PRIMA (fail-closed). Su input
   // invalido: backup predecessore + throw -> httpError(400) (mai garbage).
   async function mutate(defs, mutator) {
-    const draft = draftFrom(defs);
-    mutator(draft);
+    // Questo e' l'ALTRO scrittore: le mutazioni che arrivano dall'interfaccia.
+    // Un lock che valesse solo per l'avvio proteggerebbe il bootstrap da se'
+    // stesso e non da qui, cioe' da chi scrive davvero mentre il sistema gira.
+    //
+    // Il mutator lavora sullo stato riletto DENTRO il lock, non su quello che
+    // il chiamante aveva in mano: e' anche piu' corretto, perche' applica la
+    // modifica al presente invece che a una fotografia.
     let parsed;
     try {
-      parsed = atomicWrite(defsPath, draft);
+      parsed = aggiornaDefinizioni(defsPath, (dentro) => {
+        const draft = draftFrom(dentro);
+        mutator(draft);
+        return draft;
+      }, { propaga: true });
     } catch (e) {
+      // Due fallimenti diversi, due risposte diverse: un input invalido e' 400
+      // e non cambiera' riprovando; un lock occupato e' 409 e riprovando puo'
+      // riuscire. Confonderli manda chi legge a correggere il dato sbagliato.
+      if (e && e.code === 'FLEET_LOCK_BUSY') throw httpError(409, 'definizioni fleet occupate: riprova');
       throw httpError(400, `definizioni non valide: ${e.message}`);
     }
+    if (!parsed) throw httpError(409, 'definizioni fleet non leggibili: riprova');
     commitDefs(parsed);
     return parsed;
   }
@@ -1256,6 +1409,7 @@ module.exports = {
   // Esportate ma NON chiamate qui sopra (§bootstrap, righe ~354-358): scelta
   // deliberata, non una dimenticanza — vedi il commento su backfillDesktopEngine.
   backfillDesktopEngine,
+  riparaDesktopEngine,
   defaultDesktopEngine,
   resolveCellCwd,
   composeLaunchArgv,

package/lib/fleet/definitions.js

@@ -635,6 +635,229 @@ function parseCell(c, engineIds, engineMap = new Map(), { allowLegacyTmuxNames =
   return out;
 }
 
+
+// ---------------------------------------------------------------------------
+// aggiornaDefinizioni(p, trasforma, opts) -> definizioni risultanti
+//
+// Leggi-modifica-scrivi SOTTO LOCK. `atomicWrite` garantisce che il file non
+// resti a meta' — non che nessuno lo abbia cambiato mentre lo tenevi in mano:
+// sono due proprieta' diverse, e la prima non implica la seconda. Un audit ha
+// riprodotto la perdita su SETTE percorsi diversi (i backfill di avvio, la
+// riparazione desktop e la persistenza della migrazione): ognuno salvava,
+// osservava sul disco il valore scritto da un altro, e lo perdeva scrivendo un
+// draft costruito su uno stato precedente.
+//
+// `trasforma(defs)` riceve lo stato letto DENTRO il lock e restituisce il draft
+// da scrivere, oppure `null` per non scrivere nulla. Se il lock non si ottiene
+// entro il tempo concesso si RINUNCIA: per una migrazione opportunistica non
+// fare nulla costa un altro avvio, sovrascrivere costa un dato.
+// ---------------------------------------------------------------------------
+const LOCK_ATTESA_MS = 2000;   // quanto si insiste prima di rinunciare
+const LOCK_STALE_MS = 30000;   // oltre questa eta' il lock e' di un morto
+
+function percorsoLock(p) { return `${p}.lock`; }
+
+// La NASCITA di un processo (starttime, /proc/<pid>/stat campo 22: tick di
+// uptime a cui il processo e' partito). Un pid e' un numero RICICLATO: chiedere
+// «esiste il processo 4711?» non e' la domanda «e' ancora vivo QUEL processo
+// che prese il lock?» — se il proprietario muore e il sistema riassegna il
+// numero, kill(pid, 0) risponde «vivo» per sempre e ogni scrittura rinuncia in
+// silenzio. Due processi con lo stesso numero nascono in istanti diversi: la
+// coppia pid+nascita e' l'identita'. Null quando non e' leggibile (pid assente,
+// o sistema senza /proc: e' il modo in cui il codice vede macOS).
+function leggiStarttimeProc(pid) {
+  try {
+    const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+    // il campo comm (2) puo' contenere spazi e parentesi: si salta tutto
+    // fino all'ultima ')', i campi seguenti partono dal 3°. Il campo 22
+    // (starttime) e' quindi l'indice 19 della coda.
+    const coda = stat.slice(stat.lastIndexOf(')') + 2);
+    const st = Number(coda.split(' ')[19]);
+    return Number.isFinite(st) ? st : null;
+  } catch (_) { return null; }
+}
+
+function prendiLock(p) {
+  const lock = percorsoLock(p);
+  // La directory puo' non esistere ancora: alla prima creazione delle
+  // definizioni non c'e' nulla. Prima era `atomicWrite` a crearla, e spostando
+  // la scrittura sotto lock quell'effetto si era perso — il lock non si apriva,
+  // si rinunciava, e la creazione falliva in silenzio.
+  try { fs.mkdirSync(path.dirname(p), { recursive: true }); } catch (_) { return null; }
+  const scadenza = Date.now() + LOCK_ATTESA_MS;
+  // Il token identifica QUESTA presa, non il processo: due prese successive
+  // dello stesso pid restano distinguibili, e al rilascio si puo' verificare di
+  // stare togliendo il proprio lock e non quello di chi e' subentrato.
+  // Il TERZO campo e' la nascita di chi prende: e' quello che rende
+  // confrontabile «e' ancora vivo QUEL processo» (pid da solo non basta: e'
+  // un numero riciclato). Senza /proc non c'e' nascita da attestare e il
+  // token resta a due campi — vedere proprietarioVivo per le conseguenze.
+  const nascita = leggiStarttimeProc(process.pid);
+  const token = nascita === null
+    ? `${process.pid}:${crypto.randomBytes(8).toString('hex')}`
+    : `${process.pid}:${crypto.randomBytes(8).toString('hex')}:${nascita}`;
+  for (;;) {
+    try {
+      // 'wx' fallisce se il file esiste: e' l'esclusione mutua, in una syscall.
+      const fd = fs.openSync(lock, 'wx', 0o600);
+      try {
+        fs.writeFileSync(fd, `${token}\n`);
+      } catch (_) {
+        // Il contenuto NON e' informativo: e' l'unica cosa che rende il lock
+        // attribuibile. Se non si puo' scrivere (disco pieno, quota, errore
+        // transitorio) il lock resterebbe VUOTO: nessun pid da interrogare, e
+        // dopo 30s chiunque lo esproprierebbe mentre il presunto titolare —
+        // vivo e al lavoro, convinto di essere protetto — scrive senza mutua
+        // esclusione. Nessuna titolarita' senza token: si chiude il fd e si
+        // toglie il file APPENA CREATO (e' nostro per costruzione: 'wx'), poi
+        // si rinuncia. Un lock vuoto sul disco puo' restare solo dal relitto
+        // di un crash fra open e write — processo che non esiste piu':
+        // recuperarlo dopo la scadenza e' giusto (semantica pinnata da
+        // fleet-lock-edges «illeggibile = abbandonato»).
+        try { fs.closeSync(fd); } catch (_) { /* gia' chiuso */ }
+        try { fs.unlinkSync(lock); } catch (_) { /* gia' rimosso */ }
+        return null;
+      }
+      return { fd, token };
+    } catch (e) {
+      if (e.code !== 'EEXIST') return null; // dir non scrivibile o simili: si rinuncia
+      // Un lock abbandonato non deve bloccare per sempre — ma l'eta' da sola non
+      // dice che il proprietario sia morto: un lavoro lento e' vivo e sta usando
+      // il lock. Espropriarlo per anzianita' ROMPE la mutua esclusione, cioe'
+      // riapre esattamente il difetto che il lock chiude. Si guarda prima se il
+      // processo esiste ancora.
+      try {
+        const eta = Date.now() - fs.statSync(lock).mtimeMs;
+        if (eta > LOCK_STALE_MS && !proprietarioVivo(lock)) { fs.unlinkSync(lock); continue; }
+      } catch (_) { /* sparito nel frattempo: si riprova */ }
+      if (Date.now() >= scadenza) return null;
+      if (!dormiSincrono(25)) return null; // non si sa attendere: meglio rinunciare che consumare CPU
+    }
+  }
+}
+
+// `kill(pid, 0)` non invia nulla: chiede al kernel se quel NUMERO esiste.
+// EPERM significa che esiste e non e' nostro — vivo comunque.
+function vivoPerKernel(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e && e.code === 'EPERM'; }
+}
+
+// Il proprietario del lock e' vivo SOLO se e' ancora vivo QUEL processo.
+// Tre vie, in ordine di forza:
+//   1. token con nascita (pid:hex:starttime) e /proc leggibile: identita'
+//      CONFRONTABILE. vivo <=> il numero esiste ed e' nato nello stesso
+//      istante che il token attesta. Un numero riassegnato nasce in un
+//      istante diverso: il proprietario e' morto anche se il pid esiste.
+//   2. token con nascita ma /proc non leggibile (neanche per QUESTO
+//      processo: e' come il codice vede un sistema senza /proc, es. macOS):
+//      criterio NON CALCOLABILE — nel dubbio il lock resta, decide il kernel.
+//   3. token vecchio (pid:hex, nascita assente — lock scritti prima della
+//      correzione): identita' non confrontabile — nel dubbio il lock resta,
+//      decide il kernel. E' il buco dichiarato che resta per i lock gia'
+//      sul disco: costa una scrittura rimandata, mai un vivo espropriato.
+// L'asimmetria e' la lezione della cura precedente: dichiarare morto un vivo
+// ROMPE la mutua esclusione; dichiarare vivo un morto rimanda una scrittura.
+// `lettore` e' iniettabile per provare la via 2 dove /proc esiste eccome.
+function proprietarioVivo(lock, lettore = leggiStarttimeProc) {
+  let pid;
+  let nascita = null;
+  try {
+    const parti = String(fs.readFileSync(lock, 'utf8')).trim().split(':');
+    pid = Number.parseInt(parti[0], 10);
+    if (parti.length >= 3) {
+      const st = Number(parti[2]);
+      if (Number.isFinite(st)) nascita = st;
+    }
+  } catch (_) { return false; }
+  if (!Number.isInteger(pid) || pid <= 0) return false; // illeggibile: trattato come abbandonato
+  if (nascita !== null) {
+    // /proc leggibile per QUESTO processo? Se no, il criterio non e'
+    // calcolabile su questo sistema (non «il pid e' morto»: NON LO SO).
+    if (lettore(process.pid) === null) return vivoPerKernel(pid);
+    const sua = lettore(pid);
+    if (sua === null) return false; // /proc c'e' e quel pid non esiste: morto
+    return sua === nascita; // stesso numero, stessa nascita: e' ancora LUI
+  }
+  return vivoPerKernel(pid);
+}
+
+// Attesa sincrona senza spawnare nulla: questo percorso e' sincrono per
+// costruzione (gira nel bootstrap), quindi non c'e' un event loop da cedere.
+function dormiSincrono(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    return true;
+  } catch (_) {
+    // Senza SharedArrayBuffer non si puo' attendere senza girare a vuoto: il
+    // ciclo brucerebbe CPU per tutto il tempo concesso. Meglio dirlo al
+    // chiamante e rinunciare subito — l'aggiornamento e' opportunistico.
+    return false;
+  }
+}
+
+function rilasciaLock(p, presa) {
+  try { fs.closeSync(presa.fd); } catch (_) { /* gia' chiuso */ }
+  // Si toglie SOLO il proprio lock. Un unlink cieco, dopo che qualcun altro ha
+  // preso il lock, cancellerebbe il suo — e da li' in avanti nessuno sarebbe
+  // piu' protetto, a cascata.
+  try {
+    const dentro = String(fs.readFileSync(percorsoLock(p), 'utf8')).trim();
+    if (dentro !== presa.token) return; // subentrato qualcun altro: non e' roba nostra
+  } catch (_) { return; }
+  try { fs.unlinkSync(percorsoLock(p)); } catch (_) { /* gia' rimosso */ }
+}
+
+function aggiornaDefinizioni(p, trasforma, opts = {}) {
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+  // Di default NON si propaga: questi aggiornamenti girano nel bootstrap, dove
+  // un'eccezione non degrada — impedisce l'avvio. Prima della conversione ogni
+  // backfill aveva il suo `try/catch` attorno alla scrittura, e quella rete va
+  // conservata. Chi invece serve una richiesta dell'utente passa
+  // `propaga: true`, perche' li' un errore va riportato a chi ha chiesto.
+  const propaga = opts.propaga === true;
+  const presa = prendiLock(p);
+  if (presa === null) {
+    log('definizioni fleet: lock non ottenuto, aggiornamento rimandato');
+    // Rinunciare NON e' come non aver avuto nulla da fare, e chi propaga deve
+    // poterlo distinguere: restituendo lo stato riletto — che e' truthy — una
+    // mutazione chiesta dall'utente rispondeva OK senza aver scritto niente.
+    // L'errore ha un `code` perche' il chiamante possa dire la cosa giusta
+    // invece di confonderlo con «definizioni non valide».
+    if (propaga) {
+      const e = new Error('definizioni fleet occupate: aggiornamento non eseguito');
+      e.code = 'FLEET_LOCK_BUSY';
+      throw e;
+    }
+    return loadDefinitions(p);
+  }
+  try {
+    // La lettura sta DENTRO il lock: e' l'unico modo perche' il draft nasca da
+    // uno stato che nessun altro puo' cambiare prima che venga scritto.
+    const dentro = loadDefinitions(p);
+    if (!dentro) {
+      // `loadDefinitions` restituisce null sia per «non c'e'» sia per «c'e' ma
+      // non si legge», e la differenza qui e' tutto: creare le definizioni di
+      // default sopra un file esistente ma illeggibile CANCELLA una
+      // configurazione. Si guarda il filesystem, non il valore di ritorno.
+      let assente = false;
+      try { fs.lstatSync(p); } catch (e) { assente = e.code === 'ENOENT'; }
+      if (!assente || typeof opts.seMancante !== 'function') return null;
+      const iniziale = opts.seMancante();
+      return iniziale ? atomicWrite(p, iniziale) : null;
+    }
+    const draft = trasforma(dentro);
+    if (!draft) return dentro; // niente da fare: si esce senza scrivere
+    return atomicWrite(p, draft);
+  } catch (e) {
+    if (propaga) throw e;
+    log(`definizioni fleet: aggiornamento non riuscito (${e && e.code ? e.code : e && e.message ? e.message : 'errore'})`);
+    return loadDefinitions(p);
+  } finally {
+    rilasciaLock(p, presa);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // validateCommandTrust(command) -> {ok, reason}
 // Path assoluto, regular file, owner-executable, NON symlink (lstat), NON
@@ -823,6 +1046,9 @@ const CAPS = {
 module.exports = {
   parseDefinitions,
   validateCommandTrust,
+  aggiornaDefinizioni,
+  proprietarioVivo,
+  leggiStarttimeProc,
   validPanelUrl, PANELURL_LOOPBACK_HOSTS,
   resolveCwd,
   normalizeCwdRel,