npm - @mmmbuto/nexuscrew - Versions diffs - 0.9.1 → 0.9.3 - Mend

@mmmbuto/nexuscrew 0.9.1 → 0.9.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/CHANGELOG.md +171 -0
package/frontend/dist/assets/{index-Bu_-2-Uu.js → index-uRh_hSop.js} +19 -19
package/frontend/dist/index.html +1 -1
package/frontend/dist/version.json +1 -1
package/lib/cli/init.js +18 -3
package/lib/files/telemetry.js +89 -0
package/lib/fleet/builtin.js +258 -49
package/lib/fleet/definitions.js +226 -0
package/lib/live-host/bridge.js +82 -22
package/lib/proxy/panel-proxy.js +30 -3
package/lib/server.js +5 -0
package/package.json +1 -1
package/skills/live/SKILL.md +8 -0

package/frontend/dist/index.html CHANGED Viewed

@@ -11,7 +11,7 @@
   <meta name="apple-mobile-web-app-title" content="NexusCrew" />
   <link rel="manifest" href="/manifest.json" />
   <title>NexusCrew</title>
-  <script type="module" crossorigin src="/assets/index-Bu_-2-Uu.js"></script>
+  <script type="module" crossorigin src="/assets/index-uRh_hSop.js"></script>
   <link rel="stylesheet" crossorigin href="/assets/index-0vuhL1YP.css">
 </head>
 <body>

package/frontend/dist/version.json CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":"0.9.1"}
1	+ {"version":"0.9.2"}

package/lib/cli/init.js CHANGED Viewed

@@ -17,7 +17,7 @@ const {
   generateFleetService, installFleetService, migrationGate,
   selectProviderModeSync, fleetFileMode,
 } = require('./fleet-service.js');
-const { atomicWrite: writeFleet } = require('../fleet/definitions.js');
+const { aggiornaDefinizioni } = require('../fleet/definitions.js');
 const { defaultDefinitions } = require('../fleet/managed.js');
 const { commandExists, resolveCommand } = require('./path.js');
@@ -83,8 +83,23 @@ function ensureFleetDefaults(opts = {}) {
     if (e.code !== 'ENOENT') throw e;
   }
-  writeFleet(fleetDefsPath, defaultDefinitions());
-  return { path: fleetDefsPath, created: true, enabled: true };
+  // Fra il controllo qui sopra e la scrittura c'e' una finestra: se un altro
+  // processo crea le definizioni nel frattempo, scrivere i default sopra le sue
+  // significa cancellare una configurazione intera — non perdere una modifica.
+  // La creazione avviene quindi sotto lock, con l'esistenza RIVERIFICATA
+  // dentro: `seMancante` viene chiamata solo se il file davvero non c'e'.
+  // `propaga` perche' `created` dica il vero: senza, una rinuncia del lock
+  // restituiva lo stato riletto — truthy — e l'init dichiarava `created: true`
+  // per un file che non aveva creato.
+  let creato = null;
+  try {
+    creato = aggiornaDefinizioni(fleetDefsPath, () => null, {
+      seMancante: () => defaultDefinitions(),
+      propaga: true,
+      log: opts.log,
+    });
+  } catch (_) { creato = null; }
+  return { path: fleetDefsPath, created: Boolean(creato), enabled: true };
 }
 // Migration rule (B2): se non c'è config.json, parse la porta dal service file esistente.

package/lib/files/telemetry.js ADDED Viewed

@@ -0,0 +1,89 @@
+'use strict';
+// Telemetria per-cella: contesto LIBERO e tier 5h/7d USATI, letti dal file che
+// la statusline di Claude Code scrive in <root>/<sessione>/telemetry.json
+// (snippet documentato in docs/STATUSLINE_TELEMETRY.md, NON applicato: la
+// statusline e' dell'operatore). Il verso dei due dati e' OPPOSTO e i nomi del file lo
+// portano scritto dentro: `contextFreePct` e' quanto RESTA, `tier*UsedPct` e'
+// quanto e' STATO CONSUMATO. Confondere i versi produce una riga che dice il
+// contrario del vero e fa prendere la decisione opposta a quella giusta.
+//
+// Tre regole non opinabili, tutte implementate qui:
+//   1. TIMESTAMP OBBLIGATORIO: oltre MASSIMA_ETA_MS il dato e' morto e viene
+//      restituito null — un numero stantio che sembra fresco e' peggio di un
+//      numero assente.
+//   2. ASSENZA LEGITTIMA: le celle non-Claude (codex-vl, agy, grok, shell) non
+//      hanno quella statusline e non avranno mai questo file. File assente =
+//      null, e la riga della lista resta com'era: niente campo, niente
+//      trattino, niente «n/d».
+//   3. LETTURA TOLLERANTE: file illeggibile, JSON rotto, campi mancanti o
+//      fuori contratto — si degrada a null senza mai far fallire la lista.
+//
+// CONTRATTO del file: valori INTERI 0..100 (gia' percentuali — la
+// normalizzazione frazione→percentuale e' compito di chi scrive, vedi lo
+// snippet). Il lettore accetta SOLO interi: una frazione scritta per errore
+// (0.5 che voleva essere 50%) viene rifiutata, non arrotondata a 1% — un
+// numero sbagliato mostrato con sicurezza e' il difetto che conta, meglio
+// nessun numero.
+const fs = require('node:fs');
+const path = require('node:path');
+// La statusline aggiorna a ogni evento del modello: in una cella viva il file
+// e' sempre piu' fresco di cosi'. Cinque minuti coprono una pausa pranzo senza
+// mostrare come attuale il dato di ieri.
+const MASSIMA_ETA_MS = 5 * 60 * 1000;
+// La soglia guarda in ENTRAMBI i versi. Un ts nel futuro farebbe `ora - ts`
+// negativo: la differenza non supera MAI la massima eta' e il dato resterebbe
+// «fresco» per sempre — un orologio avanti, o uno ts scritto male, e la riga
+// mostra un numero morto che non scadra' mai. Due minuti di skew sono il
+// margine che un orologio legittimamente sforato puo' avere; oltre, il ts e'
+// rotto e il dato non esiste.
+const FUTURO_TOLLERATO_MS = 2 * 60 * 1000;
+const NOME_FILE = 'telemetry.json';
+// Accetta SOLO interi 0..100 gia' numeri. Tutto il resto e' fuori contratto
+// e non viene mostrato — in particolare null e i booleani: `Number(null)` e'
+// 0 e `Number(true)` e' 1, e un campo assente letto come «0% usato» e'
+// esattamente il numero sbagliato-mostrato-con-sicurezza che questo modulo
+// esiste per evitare.
+function percentualeIntera(valore) {
+  if (typeof valore !== 'number' || !Number.isInteger(valore)) return null;
+  if (valore < 0 || valore > 100) return null;
+  return valore;
+}
+/**
+ * Legge la telemetria di una sessione. Ritorna `{ ts, contextFreePct?,
+ * tier5hUsedPct?, tier7dUsedPct? }` con solo i campi validi, oppure null per
+ * assenza legittima, dato stantio o qualsiasi rotture. Non lancia MAI.
+ */
+function leggiTelemetria(root, sessione, ora = Date.now()) {
+  try {
+    let raw;
+    try {
+      raw = fs.readFileSync(path.join(root, String(sessione), NOME_FILE), 'utf8');
+    } catch (_) {
+      return null; // assente (o non leggibile): cella non-Claude o primo avvio
+    }
+    const dato = JSON.parse(raw);
+    if (!dato || typeof dato !== 'object' || Array.isArray(dato)) return null;
+    const ts = Number(dato.ts);
+    // Senza timestamp non c'e' freschezza da verificare: il dato non esiste.
+    if (!Number.isFinite(ts)) return null;
+    if (ora - ts > MASSIMA_ETA_MS) return null; // stantio = assente
+    if (ts - ora > FUTURO_TOLLERATO_MS) return null; // ts rotto: «fresco per sempre» non e' fresco
+    const campi = {};
+    const libero = percentualeIntera(dato.contextFreePct);
+    const t5 = percentualeIntera(dato.tier5hUsedPct);
+    const t7 = percentualeIntera(dato.tier7dUsedPct);
+    if (libero !== null) campi.contextFreePct = libero;
+    if (t5 !== null) campi.tier5hUsedPct = t5;
+    if (t7 !== null) campi.tier7dUsedPct = t7;
+    return Object.keys(campi).length ? { ts, ...campi } : null;
+  } catch (_) {
+    return null; // JSON rotto o altro: la lista non fallisce per questo
+  }
+}
+module.exports = { leggiTelemetria, MASSIMA_ETA_MS, FUTURO_TOLLERATO_MS, NOME_FILE };

package/lib/fleet/builtin.js CHANGED Viewed

@@ -26,10 +26,12 @@
 //    mutazione fleet e ogni up (§9d): passano solo status/schema/capabilities.
 //  - promptMode 'send-keys' inietta via bracketed paste; se il command e' gia'
 //    uscito (sessione morta) NON digita (§9e).
+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');
@@ -86,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
@@ -110,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
@@ -127,11 +141,73 @@ function backfillAgyEngine(defsPath, defs, cfg = {}) {
 // meccanismo condiviso (validPanelUrl in definitions.js): l'engine non ha una
 // sua strada per imporre l'URL, dichiara solo il valore, e resta sovrascrivibile
 // per-cella come qualunque altro panelUrl (vedi parseCell).
+// Risolve un eseguibile del PATH nel suo path assoluto REALE. Il realpath non
+// e' pignoleria: `validateCommandTrust` usa `lstat` e rifiuta i symlink — e in
+// molte installazioni il primo hit nel PATH e' proprio un symlink. Senza questo
+// passaggio l'engine sarebbe rifiutato dalla stessa trust boundary del
+// progetto, con un messaggio che parla di path assoluti mentre il problema e'
+// un link.
+function risolviEseguibile(nome) {
+  const dirs = String(process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    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'
+// rendeva questo engine built-in NON avviabile: veniva offerto nell'elenco e
+// rifiutato al salvataggio con «command deve essere un path assoluto», un
+// errore che descrive la forma del valore invece di dire che il comando non
+// era stato risolto.
+//
+// Se docker non e' installato si ricade sul path convenzionale: l'engine resta
+// visibile e il rifiuto diventa «non accessibile (ENOENT)», che nomina la
+// causa vera — docker manca — invece di sembrare un difetto di
+// configurazione.
 function defaultDesktopEngine() {
   return {
     id: 'desktop.local',
     label: 'Desktop',
-    command: 'docker',
+    command: risolviEseguibile('docker') || '/usr/bin/docker',
     args: ['exec', '-it', '-u', 'abc', 'ai-desktop', 'bash'],
     promptMode: 'send-keys',
     panelUrl: 'https://127.0.0.1:6901',
@@ -160,12 +236,82 @@ 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) {
-  if (!defs || defs.engines.some((engine) => engine.id === 'desktop.local')) return defs;
-  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; }
+function backfillDesktopEngine(defsPath, defs, log) {
+  if (!defs) 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
+// cio' che esiste gia'. Senza questa riparazione il difetto resterebbe
+// esattamente dove e' stato visto — su una macchina gia' configurata.
+//
+// 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, 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 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
@@ -174,13 +320,20 @@ function backfillDesktopEngine(defsPath, defs) {
 // 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,
@@ -196,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
@@ -209,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
@@ -413,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.
@@ -427,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
@@ -500,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;
   }
@@ -1201,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,