@mmmbuto/nexuscrew 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -2,6 +2,146 @@
 
 All notable changes to NexusCrew are tracked here.
 
+## 0.9.3 — 2026-08-16 — "A Receipt Is Not an Outcome"
+
+The previous release fixed the Desktop engine and shipped the fix inert. Pulling
+on that thread produced most of this one: a repair that was never called, a race
+underneath it, a lock that reopened the race it closed, and — at the end — a
+success reported for a write that never happened. A `200 OK` for a change that
+was silently dropped is worse than a refusal, because nothing downstream has any
+reason to look again.
+
+- **Every write to the fleet definitions now goes through a lock, and a
+  surrendered write is no longer reported as success.** Ten code paths did
+  read-modify-write on the same file with no mutual exclusion, so a concurrent
+  update could be read, overwritten, and lost. The lock is taken by creating a
+  file exclusively — one syscall, no window between checking and acting — and
+  its owner is identified per acquisition rather than per process. Liveness is
+  asked of the kernel: a lock is only broken when it is both old *and* its owner
+  is gone, because age alone never proved a process dead. The first version of
+  this guard evicted **live** owners, which is how a cure reopens the disease
+  it was written for; the case is now pinned by tests in both directions.
+
+  Two callers want opposite behaviour and now get it: an opportunistic
+  migration gives up in silence, while a change a person asked for **fails**
+  with its own cause — `409` when the lock is busy, `400` when the data is
+  invalid. Previously both answered `200 OK`.
+
+- **Creating the definitions for the first time also goes through the lock.**
+  `init` wrote the file directly, so a first run racing with a live service
+  could erase a configuration instead of creating one.
+
+- **The panel's own password reaches the panel.** `Authorization` was stripped
+  wholesale on the way in, so any panel behind HTTP authentication was
+  impossible to log into by construction — not misconfigured, impossible. The
+  header now travels for the schemes a panel actually uses (`Basic`, `Digest`,
+  `NTLM`, `Negotiate`) and never for a bearer token, which belongs to the
+  control plane and must not leak into a proxied application. It is a closed
+  list, not a denylist: an unknown scheme is refused rather than forwarded.
+
+- **A container that opens over the page instead of taking you away from it.**
+  Opening a cell's preview, or its desktop panel, used to mean leaving whatever
+  you were looking at. There is now one popup — closed by `Escape`, by clicking
+  outside it, never by clicking inside it, and it takes focus when it opens —
+  reached from the status dot beside each cell in the list and from the cell's
+  own tile in the grid. The panel was previously reachable **only** from an
+  enlarged cell, so opening a browser meant leaving the grid first. The popup
+  now holds all three sources — preview, live stream, desktop panel — and on
+  narrow screens they get real buttons instead of one small dot carrying three
+  meanings. Looking at a cell never selects it.
+
+  One defect found on the way, worth stating because it was invisible: the
+  popup held onto the **row** it was opened from — a single frame of a list
+  that refreshes every few seconds. Left open across a refresh it could show
+  another cell's preview, or a dead one's. It now holds the key and re-resolves
+  it on every render; a cell that disappears closes its own popup.
+
+- **The panel opened from the list is served from its own origin again.** A
+  panel reached through the new popup was passed no port, and with no port the
+  frame falls back to a relative path — same-origin with the control plane,
+  which is precisely what 0.9.1 separated so that a panel's own scripts cannot
+  reach the operator's token. The new entry point had quietly reopened it, with
+  nothing to show for it: the panel opened and worked. The port is now resolved
+  per row by the same function the grid uses, and a remote cell whose node has
+  no negotiated port still gets none rather than borrowing the local one —
+  a wrong origin is not a fallback.
+
+- **A lock is no longer held by a process that merely inherited its number.**
+  Liveness was decided by asking the kernel whether a pid existed, but pids are
+  reused: once the number was handed to an unrelated process, the lock was
+  never considered abandoned and every write to the fleet definitions gave up
+  in silence. The lock's token now also records **when** its owner started, so
+  two processes that held the same number at different times are told apart.
+  Where that cannot be read — systems without `/proc` — the lock is left alone:
+  a delayed write, never an eviction. That case is documented, not closed.
+
+  Also: a lock whose token could not be written is no longer treated as owned.
+  The write was best-effort, so a failure left an **empty** lock that named
+  nobody, and thirty seconds later a live owner could be evicted from it.
+
+- **A migration no longer overwrites work committed while it was running.**
+  The concurrency check compared a snapshot taken *after* the migration's own
+  work, so anything written during it was already inside the snapshot: the
+  comparison passed and the older state won. The baseline is now taken at the
+  source, covering the whole window.
+
+- **The cell list shows free context and tier usage, where the cell can report
+  them.** The numbers come from a small file written beside the cell's own
+  files; a documented snippet is included for producing it
+  (`docs/STATUSLINE_TELEMETRY.md`), and nothing is written automatically. Three
+  rules govern the display: a reading older than five minutes is dropped rather
+  than shown as current, cells that cannot report simply have no such line —
+  no dash, no "n/a" — and an unreadable or malformed file degrades to nothing
+  without failing the list. Values are accepted only as integers already in
+  percent: a `null` would otherwise have been converted to a perfectly credible
+  `0%` — and the same conversion was found in the documented snippet, on the
+  writing side, where the reader cannot defend against it: a zero written in
+  place of nothing is a valid integer and would have passed.
+
+  Freshness is checked in **both** directions. A reading stamped in the future
+  was never older than the limit, so it would have stayed "current" forever;
+  beyond a small tolerance for clock skew it is now dropped like any other
+  unusable value. And every number carries its own direction in its label —
+  `context 71% free · 5h used 33%` — because a comment claiming the labels said
+  so was not the same as the labels saying so, and next to a "free" the reader
+  supplies the missing word themselves.
+
+- **The voice interface knows which cell it is attached to.** It received the
+  working directory and a prompt, never an identity, so a Live session had to
+  go looking through terminal sessions to guess where it was — and could
+  describe another cell's work as its own. The bridge now always prepends the
+  designated cell's identity to the instructions it sends, alone when no
+  per-cell prompt exists. The identity travels on the bridge rather than in the
+  prompt on purpose: a prompt may legitimately be absent, and if identity
+  depended on it, a missing prompt would have meant a Live with no idea who it
+  was. The exact session name is included only when the roster declares it,
+  never inferred.
+
+  **Please note, if you set `developer_instructions` in your configuration.**
+  The bridge sends that field on every Live session now, and the consumer
+  *replaces* its configured value with what it receives rather than adding to
+  it. A cell with no per-cell prompt therefore no longer receives the global
+  developer instructions it used to get. This is accepted rather than worked
+  around: changing the field's meaning would be a new contract for every
+  client, and the intended place for a cell's own instructions is its
+  `LIVE_PROMPT.md`.
+
+- **The per-cell prompt is found on machines that name their sessions
+  anything.** Its directory was built by pinning the literal prefix `cloud-` in
+  front of the cell name, so on a host whose sessions are named otherwise the
+  file was either looked for where it does not exist, or under an invented
+  path. Both ended in "absent" — the same answer as a file that genuinely is
+  not there, so the defect hid inside the branch meant to report it. The
+  directory is now the session the roster declares, and when the roster
+  declares none there is a distinct outcome: no path is built at all, rather
+  than a prefix guessed.
+
+- **Ready-to-copy prompt templates** in `docs/live-prompt-templates/`, in
+  English, Italian and Spanish, with `docs/LIVE_PROMPT.md` describing where the
+  file goes and the four outcomes the bridge can report. They name no cell, no
+  operator and no host: the voice takes its identity from the tools at runtime,
+  so the file works as copied.
+
 ## 0.9.2 — 2026-08-16 — "Offered and Then Refused"
 
 Both defects in this release were found by using the product, not by a test —

package/lib/cli/init.js

@@ -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

@@ -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

@@ -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,

package/lib/live-host/bridge.js

@@ -17,10 +17,20 @@
 //     fallimento, la risposta è `none` col motivo: la Live parte senza
 //     puntamento, comportamento standard. Un `none` non è un errore HTTP.
 //   - MC2: il prompt per-cella (LIVE_PROMPT.md accanto ai canonici della
-//     cella) viaggia su developerInstructions di thread/start — quindi
-//     SOSTITUISCE l'iniezione globale per quella Live (rev4 LC2 emendata da
-//     rev5 MC2). Se manca non si passa nulla e l'app-server applica la sua
-//     catena globale/default: nessun gradino è un errore (MC2.4).
+//     cella) viaggia su developerInstructions di thread/start e SOSTITUISCE
+//     le developer instructions della config per quella Live (rev4 LC2
+//     emendata da rev5 MC2). La riga che decide è in codex-rs
+//     core/src/config/mod.rs: `developer_instructions.or(cfg.developer_
+//     instructions)` — l'override Some scarta il valore di config. R2
+//     (2026-08-16, verso corretto dopo audit pre-release): l'identità della
+//     cella designata viaggia SEMPRE come intestazione anteposta al campo,
+//     anche senza prompt. Il campo NON è additivo: una cella senza
+//     LIVE_PROMPT.md, che prima non passava nulla e riceveva le developer
+//     instructions della config, ora passa la sola intestazione e QUELLE
+//     NON le riceve più. Restano fuori da questa sostituzione AGENTS.md e
+//     il world state (fragment user, canale separato) e il prompt base.
+//     La via designata per le istruzioni di lavoro della Live è il
+//     LIVE_PROMPT.md della cella: viaggia nello stesso campo.
 //   - MC3: il ponte crea le proprie conversazioni con thread/start e non
 //     tocca MAI la thread di una TUI — né turn/start né thread/resume: chi
 //     guarda i metodi visti dal server deve vedere solo initialize,
@@ -62,21 +72,41 @@ const CLIENT_NAME = 'nexuscrew-live-bridge';
 const ORPHAN_GRACE_MS = 1500;
 
 // —— Prompt per-cella (rev4 LC2, nome fisso confermato da Dev 2026-08-15) ——
-// Collocazione: filesRoot/cloud-<Cella>/LIVE_PROMPT.md. Tre esiti DISTINTI,
-// perché «file non c'è» e «c'è ma non si può leggere» portano chi indaga in
-// posti diversi:
-//   applied:true                  → il testo va su developerInstructions
-//   applied:false, reason missing → ENOENT: assenza legittima (LC2.3), si
-//                                   procede senza, l'app-server applica il
-//                                   proprio gradino globale
+// Collocazione: filesRoot/<tmuxSession>/LIVE_PROMPT.md — la sessione tmux
+// ESATTA che il roster dichiara per la cella designata, la stessa fonte gia'
+// usata per l'intestazione R2 (identityHeader). NON un prefisso ricostruito a
+// mano: fino al 2026-08-16 questa funzione anteponeva 'cloud-' come default
+// universale quando il cellId non ce l'aveva gia' — su un device che chiama
+// le proprie sessioni con un prefisso diverso il file non veniva MAI trovato,
+// e l'esito era 'missing' ("assenza legittima"): il bug si mascherava
+// esattamente nel ramo che avrebbe dovuto segnalarlo. Bug trovato scrivendo
+// docs/LIVE_PROMPT.md, corretto qui.
+//
+// Quattro esiti DISTINTI, perché «non so nemmeno dove cercare», «ho cercato
+// e non c'è» e «c'è ma non si può leggere» portano chi indaga in posti
+// diversi:
+//   applied:true                        → il testo va su developerInstructions
+//   applied:false, reason session-unknown → il roster non dichiara la sessione
+//                                   tmux per questa cella: NESSUN path viene
+//                                   costruito (mai un prefisso indovinato),
+//                                   quindi non si tenta nemmeno la lettura
+//   applied:false, reason missing       → ENOENT sul path dichiarato: assenza
+//                                   legittima (LC2.3), si procede senza
+//                                   PROMPT (R2: l'intestazione identità
+//                                   viaggia comunque). ATTENZIONE: il campo
+//                                   developerInstructions viene comunque
+//                                   inviato per via dell'intestazione, e il
+//                                   consumer lo SOSTITUISCE alla propria
+//                                   configurazione invece di sommarlo — chi
+//                                   non ha prompt per-cella non riceve le
+//                                   developer instructions globali che
+//                                   riceveva prima (vedi MC2, verificato
+//                                   sulla riga che decide)
 //   applied:false, reason unreadable|empty → presente ma inutilizzabile: va
 //                                   dichiarato, mai silenziato
-function readCellPrompt(filesRoot, cellId) {
-  // Il canonico per-cella vive in filesRoot/cloud-<Cella>/. L'id cella arriva
-  // sia senza prefisso (fleet id) sia con (nome sessione tmux): si normalizza
-  // qui, una volta sola.
-  const dirName = String(cellId).startsWith('cloud-') ? String(cellId) : `cloud-${cellId}`;
-  const file = path.join(filesRoot, dirName, 'LIVE_PROMPT.md');
+function readCellPrompt(filesRoot, tmuxSession) {
+  if (typeof tmuxSession !== 'string' || !tmuxSession) return { applied: false, reason: 'session-unknown' };
+  const file = path.join(filesRoot, tmuxSession, 'LIVE_PROMPT.md');
   let raw;
   try {
     raw = fs.readFileSync(file, 'utf8');
@@ -89,6 +119,22 @@ function readCellPrompt(filesRoot, cellId) {
   return { applied: true, source: 'LIVE_PROMPT.md', text };
 }
 
+// —— Identità della Live (R2, 2026-08-16): la porta il ponte, non il prompt ——
+// Il ponte ha la designazione IN MANO (MC3.4: è la sua condizione di
+// funzionamento) e un prompt può legittimamente mancare (MC2.4): se
+// l'identità dipendesse dal prompt, l'assenza del prompt diventerebbe assenza
+// di identità — è esattamente il difetto visto sul campo (la voce andava a
+// leggere tmux per capire dove si trovava).
+//
+// Il fatto, niente di più: quale cella (id Fleet) e, se il roster la dichiara,
+// la sessione tmux esatta — quella con cui la voce raggiunge i canonici della
+// cella in ~/NexusFiles/<tmuxSession>/. Non un'instruzione di lavoro: quelle
+// vivono nel prompt per-cella, che questa intestazione PRECEDE sempre.
+function identityHeader(cellId, tmuxSession) {
+  const sessione = tmuxSession ? ` (sessione tmux ${tmuxSession})` : '';
+  return `Live NexusCrew agganciata alla cella ${cellId}${sessione}.`;
+}
+
 // —— Client on-demand del socket di controllo (sezione protocollo sopra) ——
 // Una sola richiesta per connessione: aperta, handshake, thread/start, chiusa.
 // Le eventuali notifiche broadcast che arrivano nel frattempo vengono ignorate
@@ -308,7 +354,9 @@ function createLiveBridge({
     // qualunque altro engine la Live lavora ATTRAVERSO la cella e il ponte non
     // ha nulla da creare qui.
     const engine = String(cell.engine || '');
-    const prompt = readCellPrompt(root, snap.hostCell);
+    // Stessa fonte dell'intestazione qui sotto: la sessione tmux che il
+    // roster dichiara, mai il cellId ricostruito con un prefisso indovinato.
+    const prompt = readCellPrompt(root, cell.tmuxSession);
 
     if (!engine.startsWith('codex-vl')) {
       const out = {
@@ -322,12 +370,21 @@ function createLiveBridge({
       return out;
     }
 
+    // R2: l'identità viaggia SEMPRE, anteposta al prompt quando c'è. Il campo
+    // non è mai più assente: senza LIVE_PROMPT.md porta la sola intestazione
+    // — e poiché il campo SOSTITUISCE le developer instructions della config
+    // (vedi MC2: la .or() in config/mod.rs), quella cella non le riceve più.
+    const intestazione = identityHeader(snap.hostCell, cell.tmuxSession);
+    const developerInstructions = prompt.applied
+      ? `${intestazione}\n\n${prompt.text}`
+      : intestazione;
+
     let started;
     try {
       started = await startThreadOnControlSocket({
         socketPath: cfg.liveBridgeSocketPath,
         cwd: cell.cwd,
-        developerInstructions: prompt.applied ? prompt.text : undefined,
+        developerInstructions,
         timeoutMs: cfg.liveBridgeTimeoutMs,
         WebSocket,
         log,
@@ -347,12 +404,15 @@ function createLiveBridge({
       at: now(),
     };
     // LC1.4: il puntamento è visibile lato nostro — log con cella, thread e
-    // prompt applicato. È il "dirottamento dichiarato" del contratto.
-    log(`[live-bridge] Live puntata su ${snap.hostCell}: thread ${started.threadId} (cwd ${started.cwd}, prompt ${prompt.applied ? 'per-cella applicato (sostituisce il globale)' : `non applicato (${promptEcho.reason})`})`);
+    // prompt applicato. È il "dirottamento dichiarato" del contratto. Il
+    // campo SOSTITUISCE le developer instructions della config (MC2, la
+    // .or() in config/mod.rs): il log lo dichiara, perché chi lo legge sappia
+    // cosa quella Live NON riceve.
+    log(`[live-bridge] Live puntata su ${snap.hostCell}: thread ${started.threadId} (cwd ${started.cwd}, identità nell'intestazione, prompt ${prompt.applied ? 'per-cella applicato' : `non applicato (${promptEcho.reason})`}, sostituisce le developer instructions di config)`);
     return out;
   }
 
-  return { resolveForLive, readCellPrompt: (cellId) => { const { text, ...rest } = readCellPrompt(root, cellId); return rest; } };
+  return { resolveForLive, readCellPrompt: (tmuxSession) => { const { text, ...rest } = readCellPrompt(root, tmuxSession); return rest; } };
 }
 
 let cachedVersion = null;

package/lib/proxy/panel-proxy.js

@@ -89,9 +89,23 @@ function stripLocalTokenQuery(search) {
 // sessione del control plane, esattamente cio' che l'Authorization rimossa
 // doveva impedire. E `x-forwarded-*` da un client sono valori che un pannello
 // potrebbe credere veri. Rilievo di un audit indipendente.
-function isStrippedRequestHeader(key) {
+function isStrippedRequestHeader(key, value) {
   if (HOP_BY_HOP.has(key)) return true;
-  if (key === 'authorization' || key === 'cookie' || key === 'host') return true;
+  if (key === 'cookie' || key === 'host') return true;
+  // `authorization` NON si strippa in blocco: lo schema dice di chi e'.
+  //
+  // `Bearer` e' il nostro token del control plane e non deve mai raggiungere il
+  // container — e' la ragione per cui questo strip esiste. Ma un pannello
+  // protetto da password risponde `401 WWW-Authenticate: Basic`, il browser
+  // chiede le credenziali all'utente e le rimanda: buttando via ANCHE quelle,
+  // il pannello ripresentava il prompt all'infinito e il login era impossibile
+  // per costruzione. Sono credenziali che l'utente ha inserito PER il pannello,
+  // in risposta a una sua richiesta: appartengono a lui.
+  //
+  // Dichiarato: se qualcuno mette una basic auth propria davanti a NexusCrew,
+  // quella credenziale raggiungerebbe il pannello. Non e' il nostro schema di
+  // autenticazione e non e' una configurazione che produciamo.
+  if (key === 'authorization') return !credenzialeDelPannello(value);
   // `referer` porterebbe il ticket d'ingresso (viaggiava in query sulla prima
   // richiesta dell'iframe) fino al pannello: al container non deve arrivare
   // NESSUNA credenziale, nemmeno di seconda mano.
@@ -101,10 +115,23 @@ function isStrippedRequestHeader(key) {
   return false;
 }
 
+// ELENCO CHIUSO di cio' che si inoltra, non di cio' che si toglie: un valore
+// sconosciuto non deve poter passare per omissione. Sono gli schemi con cui un
+// server web chiede le credenziali al browser — quelli che l'utente puo' aver
+// inserito in risposta a un `401` del pannello. Tutto il resto, `Bearer`
+// compreso, resta di qua.
+const SCHEMI_DEL_PANNELLO = /^(basic|digest|ntlm|negotiate)\s/i;
+
+function credenzialeDelPannello(value) {
+  const primo = Array.isArray(value) ? value[0] : value;
+  if (typeof primo !== 'string') return false;
+  return SCHEMI_DEL_PANNELLO.test(primo.trim());
+}
+
 function forwardHeaders(headers, targetHost) {
   const out = {};
   for (const [k, v] of Object.entries(headers || {})) {
-    if (isStrippedRequestHeader(k.toLowerCase())) continue;
+    if (isStrippedRequestHeader(k.toLowerCase(), v)) continue;
     out[k] = v;
   }
   // L'host deve essere quello della destinazione: un pannello che genera

package/lib/server.js

@@ -19,6 +19,7 @@ const { loadOrCreateToken, verify } = require('./auth/token.js');
 const { requireToken, bearerFrom } = require('./auth/middleware.js');
 const { filesRoutes } = require('./files/routes.js');
 const { createOutboxWatcher } = require('./files/watcher.js');
+const { leggiTelemetria } = require('./files/telemetry.js');
 const VERSION = require('../package.json').version;
 const { transcribe } = require('./voice/transcribe.js');
 const { selectProvider } = require('./fleet/provider.js');
@@ -753,6 +754,10 @@ function createServer(opts = {}) {
           status: working ? (s.status || sample?.status || '') : '',
           outbox: sum[s.name] || { count: 0, latest: 0 },
           preview: sample?.preview ?? null,
+          // Contesto libero e tier usati, dove la cella li pubblica (celle
+          // Claude via statusline). Null per tutte le altre — assenza
+          // legittima, non un trattino: la riga resta com'era.
+          telemetry: leggiTelemetria(cfg.filesRoot, s.name),
         };
       }));
       res.json({ sessions: enriched });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {

package/skills/live/SKILL.md

@@ -83,6 +83,14 @@ owning node, not a retry from the requester.
   with nothing designated still answers `GET` with `hostCell: null` — a valid
   state, distinct from "not permitted to ask".
 
+## The per-cell voice prompt
+
+Once a session lands on a host cell, a native Live (engine `codex-vl*`)
+always sends `thread/start` an identity header naming the designated cell
+and its exact tmux session, and appends a per-cell prompt file's text after
+it when one exists. See [The Live per-cell prompt](../../docs/LIVE_PROMPT.md)
+for where the file goes and the ready-to-copy IT/EN/ES templates.
+
 ## Dependencies
 
 **Bundled:** this is a NexusCrew core feature. No external MCP companion or