@mmmbuto/nexuscrew 0.8.57 → 0.9.0

package/lib/fleet/prompt-delivery.js

@@ -90,7 +90,7 @@ function tailOf(text) {
 
 // classifyPane(captured, client) -> PANE_STATES enum. Pura, senza dipendenze:
 // il testo resta dentro la funzione, fuori esce solo lo stato bounded.
-// client: 'kimi' | 'claude' (gli altri non passano mai di qui: 'unknown').
+// client: 'kimi' | 'claude' | 'vl' (gli altri non passano mai di qui: 'unknown').
 function classifyPane(captured, client) {
   const text = typeof captured === 'string' ? captured : '';
   if (!text.trim()) return 'unknown';
@@ -112,9 +112,57 @@ function classifyPane(captured, client) {
     // not-ready (gia' valutati sopra: il cursore ❯ dei dialoghi non inganna).
     return /^\s*❯/m.test(tail) ? 'ready' : 'unknown';
   }
+  if (client === 'vl') {
+    // READY positivo VL (TUI Vivling): la riga di stato in coda porta il
+    // marcatore stabile prefisso `vivling` + stato `[o]` e la coda
+    // `esc quit · ^y yield`. Misurato 2026-08-14 su due backend
+    // (zai-a-coding, opencode-go): il marcatore e' stabile a prescindere dal
+    // backend, dal writer-id (e<numero>) e dal contatore (↑<numero>).
+    //
+    // NON si classifica 'busy' dal contenuto: su alcuni backend il ragionamento
+    // non viene renderizzato e il pane resta IDENTICO mentre la cella lavora
+    // (gli stati [?] e [<<] esistono ma non sono affidabili per il busy). Il
+    // busy di vl si rileva con la sonda esterna (CPU del demone, connessione
+    // :443, figli), non di qui; qui si dice solo "pronta" ([o]) o "non pronta".
+    // Il titolo pane NON reca lo spinner braille (vl.bin non contiene "tmux"):
+    // il ready si prende dalla riga di stato, MAI dal titolo (che resta idle).
+    return /vivling\s+\[o\].*esc quit · \^y yield/.test(tail) ? 'ready' : 'unknown';
+  }
   return 'unknown';
 }
 
+// vlPaneReadiness(tmuxBin, target, opts) -> { ready, degraded }
+// DEC1: content-readiness di una cella vl via pane — il marcatore [o] + coda
+// `esc quit · ^y yield` riconosciuto da classifyPane(text,'vl'). E' il PUNTO DI
+// INNESTO della readiness vl: quando arrivera' l'adapter di runtime, la
+// readiness si misurera' sul socket di controllo (vl-core/src/transport.rs) e
+// non sul pane — si sostituisce questa funzione, non si cercano capture-pane
+// sparsi nel codice. Un solo chiamante (runtime.js, ramo vl post-liveness).
+//
+// MAI fail-closed su un'euristica di testo. Se entro il timeout il marcatore
+// non compare (backend che cambia la riga di stato, pane non ancora stabile),
+// DEGRADA: ritorna {ready:true, degraded:true} e procede come se fosse pronta.
+// Una cella che oggi parte deve partire anche domani: il peggio ammesso e'
+// tornare al comportamento di oggi (avvio sulla sola liveness), MAI "non parte
+// piu'". Il chiamante lascia traccia del degrado (readinessDegraded nel risultato).
+async function vlPaneReadiness(tmuxBin, target, {
+  env, timeoutMs = 12000, pollMs = 400, captureImpl, sleepImpl, nowImpl,
+} = {}) {
+  const sleepFn = sleepImpl || sleep;
+  const now = nowImpl || Date.now;
+  const capture = captureImpl || (async () => {
+    const r = await tmuxExec(tmuxBin, ['capture-pane', '-p', '-t', target], { env, timeoutMs: 2000 });
+    return r.err ? null : r.stdout;
+  });
+  const deadline = now() + Math.max(0, timeoutMs);
+  for (;;) {
+    const text = await capture();
+    if (text !== null && classifyPane(text, 'vl') === 'ready') return { ready: true, degraded: false };
+    if (now() >= deadline) return { ready: true, degraded: true };
+    await sleepFn(pollMs);
+  }
+}
+
 function clampInt(value, dflt, min, max) {
   const n = Number(value);
   if (!Number.isFinite(n)) return dflt;
@@ -271,5 +319,5 @@ function actionRequiredFor(client, provider, delivery) {
 
 module.exports = {
   PANE_STATES, DELIVERY_STATES, ACTION_CODES, RECOVERY_SLUGS,
-  classifyPane, deliverBootstrapPrompt, waitDeliveryReport, actionRequiredFor,
+  classifyPane, deliverBootstrapPrompt, waitDeliveryReport, actionRequiredFor, vlPaneReadiness,
 };

package/lib/fleet/provider.js

@@ -21,7 +21,7 @@ async function selectProvider(cfg = {}) {
   if (cfg.fleetSeam) return { mode: 'seam', reason: 'fleet iniettata (seam di test)', fleet: cfg.fleetSeam };
   if (cfg.fleetEnabled === false) return disabled('fleet disabilitata (fleetEnabled=false)');
   if (cfg.builtinEnabled === false) return disabled('fleet builtin disabilitata (builtinEnabled=false)');
-  const fleet = await createBuiltinFleet({ ...cfg, fleetProviderReason: 'NexusCrew builtin fleet' });
+  const fleet = await createBuiltinFleet({ ...cfg, cellLeaseEnabled: cfg.cellLeaseEnabled, fleetProviderReason: 'NexusCrew builtin fleet' });
   if (!fleet.available) return disabled(fleet.reason || 'fleet.json mancante o invalido (fail-closed)');
   return { mode: 'builtin', reason: 'NexusCrew builtin fleet', fleet };
 }

package/lib/fleet/runtime.js

@@ -25,7 +25,7 @@ const {
   waitAlive, waitStablePane, injectPrompt,
   redactSecrets, sanitizeEarlyDiagnostic,
 } = require('./launch.js');
-const { waitDeliveryReport, actionRequiredFor } = require('./prompt-delivery.js');
+const { waitDeliveryReport, actionRequiredFor, vlPaneReadiness } = require('./prompt-delivery.js');
 
 // TTL della cache status (ms): scaduto, status rilegge tmux + defs da disco.
 const STATUS_TTL_MS = 2000;
@@ -41,7 +41,7 @@ function findEngine(defs, id) { return defs.engines.find((e) => e.id === id) ||
 //   e' tornato unavailable su garbage).
 // ---------------------------------------------------------------------------
 function createBuiltinRuntime(ctx) {
-  const { cfg, home, defsPath, tmuxBin, readonly, launchBroker, boot, ensureProtection } = ctx;
+  const { cfg, home, defsPath, tmuxBin, readonly, launchBroker, leaseManager, boot, ensureProtection } = ctx;
   let cache = { at: 0, defs: boot, sessions: new Set() };
 
   function reloadDefs() {
@@ -73,7 +73,15 @@ function createBuiltinRuntime(ctx) {
   // La directory cella e il trasporto MCP dipendono soltanto da definizioni e
   // tmux. Tenerla separata dai cataloghi modello evita che un binario esterno
   // lento trasformi `/api/cells` in un falso guasto della flotta.
-  async function cellStatus() {
+  // `includeCwd` di default NEGATO. La cwd reale e' un path assoluto della
+  // macchina, e questa vista alimenta anche `GET /fleet/status`, che e' nella
+  // allowlist federata con inoltro trasparente: senza questo default, la
+  // directory di ogni cella uscirebbe verso ogni peer. Serve a un consumatore
+  // solo — il ponte Live, che la chiede esplicitamente e in-processo — quindi
+  // e' lui a doverla chiedere, non tutti gli altri a doversene ricordare.
+  // Il backup vieta gia' le cwd assolute per la stessa ragione: sono specifiche
+  // del dispositivo. Rilievo di un audit indipendente.
+  async function cellStatus({ includeCwd = false } = {}) {
     if (Date.now() - cache.at > STATUS_TTL_MS) {
       reloadDefs();                          // pick-up di edit esterne/file
       const sessions = await refreshSessions();
@@ -92,16 +100,37 @@ function createBuiltinRuntime(ctx) {
       const effectivePolicy = ['pi', 'shell'].includes(engineDef?.managed?.client)
         ? 'standard'
         : (remembered || engineDefault || '');
+      // D8: panelUrl per-cella vince su quello precompilato dall'engine (es.
+      // desktop.local), che a sua volta e' il default. Stessa forma di
+      // engineDef gia' usata sopra per la permission policy: un valore
+      // presente qui e' gia' passato da validPanelUrl a monte (parseEngine/
+      // parseCell), quindi si copia, non si ri-valida.
+      const panelUrl = c.panelUrl || engineDef?.panelUrl || '';
       return {
         // `cell` resta l'id: e' la chiave di indirizzamento. `label` e' il nome
         // leggibile e viaggia accanto, senza mai sostituirlo.
         cell: c.id, label: c.label || '', tmuxSession: c.tmuxSession, engine: c.engine,
+        // cwd reale della cella (resolveCwd), per il ponte Live (fetta 3): la
+        // thread ponte parte con la directory della cella designata. Null se
+        // la definizione non risolve: il ponte lo dichiara, non lo indovina.
+        // Presente SOLO su richiesta esplicita: vedi il commento su cellStatus.
+        ...(includeCwd ? { cwd: resolveCwd(c.cwd, home) || null } : {}),
         model: c.model || '', models: { ...(c.models || {}) },
         permissionPolicy: effectivePolicy,
         permissionPolicies: { ...(c.permissionPolicies || {}) },
         active: alive, boot: c.boot, tmux: alive,
         supervised: true, keepalive: true,
+        // Seam lease↔designazione (2026-08-15): il facade possiede leaseManager
+        // nel ctx e qui lo esprime. `active` resta la verita' tmux (con
+        // remain-on-exit la sessione sopravvive alla morte del supervisore);
+        // `lease` e' la verita' di supervisione: live|grace|expired|none, o
+        // 'unavailable' senza leaseManager — il fail-open dichiarato delle
+        // route live-host, mai un valore che finga una verifica avvenuta.
+        lease: leaseManager && typeof leaseManager.status === 'function'
+          ? ((leaseManager.status(c.id) || {}).state || 'none')
+          : 'unavailable',
         rc: '', key: '', degraded: false, // supervisor vivo <=> sessione tmux viva
+        panelUrl,
       };
     });
     return {
@@ -113,8 +142,8 @@ function createBuiltinRuntime(ctx) {
     };
   }
 
-  async function status() {
-    const base = await cellStatus();
+  async function status(opts = {}) {
+    const base = await cellStatus(opts);
     const needsOllama = cache.defs.engines.some((e) => e.managed?.provider === 'ollama-cloud');
     const needsPi = cache.defs.engines.some((e) => e.managed?.client === 'pi');
     // Le discovery esterne hanno budget propri. Avviarle in parallelo mantiene
@@ -189,7 +218,11 @@ function createBuiltinRuntime(ctx) {
     const child = composeClientInvocation(launchEngine, cell);
     let ticket;
     try {
-      ticket = await launchBroker.issue({
+      let leaseInfo = null;
+    if (leaseManager) {
+      try { leaseInfo = await leaseManager.track(cell.id); } catch (_) { leaseInfo = null; }
+    }
+    ticket = await launchBroker.issue({
         command: child.command,
         args: child.args,
         env: {
@@ -197,6 +230,7 @@ function createBuiltinRuntime(ctx) {
           ...launchEngine.env,
           NEXUSCREW_MCP_SESSION: cell.tmuxSession,
         },
+        ...(leaseInfo ? { lease: { cellId: cell.id, launchEpoch: leaseInfo.launchEpoch, stablePath: leaseInfo.stablePath } } : {}),
         supervise: {
           enabled: !launchEngine.shellOneShot,
           initialReadyMs: Math.max(50, Math.min(30000, Number(readyMs) || 500)),
@@ -394,6 +428,18 @@ function createBuiltinRuntime(ctx) {
         ['set-option', '-w', '-t', readiness.target, 'remain-on-exit', 'off'], { env: minimalEnv(), timeoutMs: 2000 });
     }
 
+    // DEC1: content-readiness vl (marcatore [o] nel pane). MAI fail-closed: se
+    // entro il timeout il marcatore non compare DEGRADA e procede come se pronta
+    // (una cella che parte oggi deve partire anche domani), lasciando traccia
+    // nel risultato. vlPaneReadiness e' il punto di innesto sostituibile quando
+    // la readiness si misurera' sul socket (adapter), non sul pane. Solo vl: gli
+    // altri client non hanno content-readiness da pane.
+    let readinessDegraded = false;
+    if (engine.managed && engine.managed.client === 'vl' && readiness.target) {
+      const vlReady = await vlPaneReadiness(tmuxBin, readiness.target, { env: minimalEnv() });
+      if (vlReady.degraded) readinessDegraded = true;
+    }
+
     // Il command Shell e' partito ed e' ancora vivo dopo la finestra di
     // readiness: la cella deve risultare attiva (per CLI interattive come agy),
     // poi tornera' inattiva quando il processo terminera' naturalmente.
@@ -450,6 +496,7 @@ function createBuiltinRuntime(ctx) {
     return {
       ok: true, cell: cellId, session: cell.tmuxSession, prompt,
       ...(actionRequired ? { actionRequired } : {}),
+      ...(readinessDegraded ? { readinessDegraded: true } : {}),
     };
   }
 

package/lib/live-host/bridge.js

@@ -0,0 +1,369 @@
+'use strict';
+// lib/live-host/bridge.js — il ponte Live (fetta 3, contratto rev5 + rev4 LC).
+//
+// Esposizione: POST /api/live-host/bridge (montata in routes.js, stesso
+// requireToken e stessa policy local-only del proxy: LOCAL_ONLY_PREFIXES copre
+// l'intero prefisso /api/live-host, quindi nessun peer federato può innescare
+// il ponte). La chiamata rappresenta l'avvio di una Live sul nodo: chi la fa è
+// il lato app-server della stessa feature (non costruito qui), e il risultato
+// dice su che cosa quella Live va a operare.
+//
+// Invarianti (contratto fetta 3):
+//   - MC1: la designazione si legge con UNA GET su loopback verso
+//     /api/live-host, autenticata col token del nodo. Nessun accesso diretto
+//     allo store: la route è l'unica verità, `eligible` non si ricalcola.
+//   - MC1.5 / JC3.3: nessuna attesa introdotta. Ogni fase ha il limite
+//     dichiarato cfg.liveBridgeTimeoutMs; oltre quello, o su qualunque
+//     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).
+//   - 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,
+//     initialized e thread/start. Per questo l'aggancio funziona anche su una
+//     cella che sta già processando un turno: conversazioni separate, nessuna
+//     interruzione (rev1 HC2/rev2 JC4).
+//   - MC3.3: la connessione al socket di controllo è ON-DEMAND (connect →
+//     handshake → thread/start → close), mai permanente: la fuga notifiche
+//     notata in rev5 riguarda i client permanenti.
+//   - MC3.4: il ponte opera SOLO sulla cella designata — non accetta target
+//     dal chiamante, la designazione è la condizione (LC3).
+//   - MC0: isolabile — cfg.liveBridgeEnabled=false e il ponte non si connette
+//     mai, non fa GET, risponde `none` senza toccare nulla.
+//
+// Protocollo del socket di controllo (misurato sul runtime 2026-08-15):
+// WebSocket (text frame) sopra unix socket, JSON-RPC. Handshake: request
+// `initialize` → response {userAgent, codexHome} → notifica `initialized`
+// (senza params). Poi `thread/start` {cwd, developerInstructions?} → response
+// {thread:{id}, cwd}. Il socket è 0600 dell'utente: il confine è quello
+// (MC1.3), non c'è autenticazione applicativa.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// ws+unix:// è supportato nativamente da ws >= 8 (isIpcUrl): il path prima dei
+// `:` è il socket, dopo è la resource. Iniettabile per i test.
+let WebSocketImpl = null;
+function defaultWebSocket() {
+  if (!WebSocketImpl) WebSocketImpl = require('ws');
+  return WebSocketImpl;
+}
+
+const CLIENT_NAME = 'nexuscrew-live-bridge';
+// Finestra concessa alla risposta di una thread/start ancora in volo quando il
+// ponte ha gia' dichiarato l'esito: se arriva, la thread e' nata davvero e la
+// chiudiamo. Breve di proposito — non allunga la risposta a chi ha chiesto il
+// ponte, che e' gia' stata data.
+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
+//   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');
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return { applied: false, reason: 'missing' };
+    return { applied: false, reason: 'unreadable', detail: String((e && e.code) || e) };
+  }
+  const text = String(raw).trim();
+  if (!text) return { applied: false, reason: 'empty' };
+  return { applied: true, source: 'LIVE_PROMPT.md', text };
+}
+
+// —— 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
+// e la finestra resta minima.
+function startThreadOnControlSocket({
+  socketPath, cwd, developerInstructions, timeoutMs,
+  WebSocket = defaultWebSocket(), now = () => Date.now(), log = () => {},
+}) {
+  return new Promise((resolve, reject) => {
+    const deadline = now() + timeoutMs;
+    let settled = false;
+    let nextId = 0;
+    const pending = new Map();
+    let ws;
+    // Id della richiesta thread/start: serve a riconoscerne la risposta anche
+    // quando arriva dopo che abbiamo gia' risolto, per non lasciare orfana una
+    // thread che nel frattempo e' nata davvero.
+    let startRequestId = null;
+    let orphanTimer = null;
+
+    // Chiusura del socket, separata dalla risoluzione della promessa: chi ha
+    // chiesto il ponte riceve subito la risposta, la pulizia puo' prendersi
+    // qualche istante in piu'.
+    const chiudi = () => {
+      try {
+        if (!ws) return;
+        // Se non e' OPEN, `close()` non fa nulla e la connessione resta
+        // appesa: su un socket in CONNECTING l'evento 'open' scatterebbe DOPO,
+        // e senza la guardia in cima al gestore aprirebbe una thread su un
+        // ponte gia' risolto. `terminate()` la chiude davvero.
+        if (ws.readyState === WebSocket.OPEN) ws.close(1000); else ws.terminate();
+      } catch (_) { /* best effort */ }
+    };
+
+    const done = (err, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      // Se una thread/start e' ancora in volo, la thread potrebbe nascere UN
+      // ISTANTE DOPO che abbiamo dichiarato il fallimento: chiudere ora la
+      // lascerebbe orfana, viva e senza nessuno che la usi. Diamo una finestra
+      // breve per riceverne la risposta e chiuderla noi. E' best effort, ma la
+      // differenza fra "nessuno la chiude" e "quasi sempre la chiudiamo" e'
+      // esattamente il difetto.
+      if (startRequestId !== null && pending.has(startRequestId)) {
+        orphanTimer = setTimeout(chiudi, ORPHAN_GRACE_MS);
+      } else {
+        chiudi();
+      }
+      if (err) reject(err); else resolve(value);
+    };
+    const timer = setTimeout(() => {
+      done(Object.assign(new Error('control socket timeout'), { code: 'ETIMEOUT' }));
+    }, timeoutMs);
+
+    try {
+      ws = new WebSocket(`ws+unix://${socketPath}:/`, { handshakeTimeout: timeoutMs });
+    } catch (e) {
+      done(Object.assign(new Error(`control socket: ${e.message}`), { code: 'ESOCKET' }));
+      return;
+    }
+
+    const send = (obj) => ws.send(JSON.stringify(obj));
+    const request = (method, params) => new Promise((res, rej) => {
+      const id = ++nextId;
+      pending.set(id, { res, rej });
+      send({ jsonrpc: '2.0', id, method, params });
+    });
+    // Come `request`, ma comunica l'id al chiamante prima di attendere: serve a
+    // riconoscere la risposta tardiva di thread/start.
+    const requestTracked = (method, params, onId) => new Promise((res, rej) => {
+      const id = ++nextId;
+      pending.set(id, { res, rej });
+      onId(id);
+      send({ jsonrpc: '2.0', id, method, params });
+    });
+
+    ws.on('open', async () => {
+      // Il ponte puo' essere gia' stato risolto (timeout durante l'handshake):
+      // procedere qui aprirebbe una thread che nessuno aspetta piu'.
+      if (settled) { chiudi(); return; }
+      try {
+        await request('initialize', {
+          clientInfo: { name: CLIENT_NAME, title: 'NexusCrew Live Bridge', version: bridgeVersion() },
+          capabilities: { experimentalApi: true },
+        });
+        send({ jsonrpc: '2.0', method: 'initialized' }); // notifica, senza params
+        const params = { cwd };
+        if (developerInstructions) params.developerInstructions = developerInstructions;
+        const out = await requestTracked('thread/start', params, (id) => { startRequestId = id; });
+        const threadId = out && out.thread && out.thread.id;
+        if (!threadId) {
+          done(Object.assign(new Error('thread/start senza thread.id'), { code: 'EPROTO' }));
+          return;
+        }
+        done(null, { threadId, cwd: out.cwd || cwd });
+      } catch (e) {
+        done(e);
+      }
+    });
+
+    ws.on('message', (data) => {
+      let msg;
+      try { msg = JSON.parse(String(data)); } catch (_) { return; /* frame non JSON: ignorato */ }
+      // Risposta tardiva a thread/start su un ponte gia' risolto: la thread
+      // ESISTE. Chiuderla e' l'unica cosa che la distingue da un'orfana.
+      if (settled && msg && msg.id != null && msg.id === startRequestId) {
+        pending.delete(msg.id);
+        const threadId = msg.result && msg.result.thread && msg.result.thread.id;
+        if (threadId) {
+          try { send({ jsonrpc: '2.0', id: ++nextId, method: 'thread/stop', params: { threadId } }); } catch (_) { /* best effort */ }
+          log({ event: 'live-bridge', outcome: 'orphan-thread-stopped', threadId });
+        }
+        if (orphanTimer) { clearTimeout(orphanTimer); orphanTimer = null; }
+        setTimeout(chiudi, 50);
+        return;
+      }
+      if (msg && msg.id != null && pending.has(msg.id)) {
+        const waiter = pending.get(msg.id);
+        pending.delete(msg.id);
+        if (msg.error) waiter.rej(Object.assign(new Error(msg.error.message || 'jsonrpc error'), { code: 'ERPC', detail: msg.error }));
+        else waiter.res(msg.result);
+        return;
+      }
+      // Notifiche broadcast e risposte non attese: ignorate (connessione
+      // on-demand, la finestra di esposizione alla fuga MC3.3 è minima).
+    });
+
+    ws.on('error', (e) => done(Object.assign(new Error(`control socket: ${e.message}`), { code: 'ESOCKET' })));
+    ws.on('close', () => {
+      if (!settled) done(Object.assign(new Error('control socket chiuso prima della risposta'), { code: 'ESOCKET' }));
+    });
+    void deadline; // il timer copre l'intera finestra, il deadline è informativo
+  });
+}
+
+// —— Il ponte ——
+function createLiveBridge({
+  cfg,
+  fleetP,
+  tokenGet,
+  filesRoot,
+  fetchImpl = globalThis.fetch,
+  WebSocket,
+  now = () => Date.now(),
+  log = () => {},
+}) {
+  const root = filesRoot || cfg.filesRoot || path.join(os.homedir(), 'NexusFiles');
+
+  const none = (reason, extra) => ({ mode: 'none', reason, ...(extra || {}), at: now() });
+
+  // MC1: la designazione si legge dalla ROUTE, con il token del nodo, entro
+  // il limite dichiarato. retry no, cache no: una lettura per avvio Live.
+  async function readDesignation() {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), cfg.liveBridgeTimeoutMs);
+    try {
+      const res = await fetchImpl(`http://127.0.0.1:${cfg.port}/api/live-host`, {
+        headers: { authorization: `Bearer ${tokenGet()}` },
+        signal: ctrl.signal,
+      });
+      if (res.status !== 200) {
+        const e = new Error(`live-host HTTP ${res.status}`);
+        e.code = 'EHTTP';
+        throw e;
+      }
+      return await res.json();
+    } finally {
+      clearTimeout(t);
+    }
+  }
+
+  async function rosterCell(cellId) {
+    const fleet = await fleetP;
+    if (!fleet || fleet.available !== true) return null;
+    const statusFn = fleet && (typeof fleet.status === 'function' ? fleet.status : fleet.cellStatus);
+    if (typeof statusFn !== 'function') return null;
+    // La cwd va chiesta: la vista pubblica non la porta piu', perche' finiva
+    // anche nella risposta federata di /fleet/status.
+    const st = await statusFn.call(fleet, { includeCwd: true });
+    const cells = Array.isArray(st && st.cells) ? st.cells : [];
+    return cells.find((c) => c && c.cell === cellId) || null;
+  }
+
+  // Risolve il puntamento per l'avvio di una Live. Sempre una risposta utile:
+  // i `none` sono modi legittimi di non puntare, e il reason distingue le
+  // cause (designazione assente, cella non idonea, fallback su fallimento).
+  async function resolveForLive() {
+    if (cfg.liveBridgeEnabled !== true) return none('bridge-disabled');
+
+    let snap;
+    try {
+      snap = await readDesignation();
+    } catch (e) {
+      const aborted = e && (e.name === 'AbortError' || /aborted/i.test(String(e.message)));
+      return none(aborted ? 'live-host-timeout' : 'live-host-unreachable');
+    }
+    if (!snap || snap.hostCell == null) return none('no-designation');
+    // Tre condizioni diverse, tre nomi: la designazione dichiarata non
+    // eleggibile dall'hub, la cella che non esiste piu' nel roster, e la cella
+    // che c'e' ma e' spenta. Un nome solo mandava a guardare l'hub anche quando
+    // il problema era una sessione chiusa. Rilievo di un audit indipendente.
+    if (snap.eligible !== true) return none('host-ineligible');
+
+    let cell;
+    try {
+      cell = await rosterCell(snap.hostCell);
+    } catch (_) {
+      cell = null;
+    }
+    if (!cell) return none('host-cell-unknown');
+    if (cell.active !== true) return none('host-cell-inactive');
+    if (typeof cell.cwd !== 'string' || !cell.cwd) return none('cell-cwd-unknown');
+
+    // JC2: la modalità è una funzione dell'engine, non una scelta. Nativa solo
+    // su engine codex-vl (il thread ponte vive nell'app-server del fork); per
+    // 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);
+
+    if (!engine.startsWith('codex-vl')) {
+      const out = {
+        mode: 'tmux', cell: snap.hostCell, engine: cell.engine || null, cwd: cell.cwd,
+        // JC5.5: in modalità tmux le regole le applica la cella; nessuna
+        // iniezione da parte del ponte.
+        prompt: { applied: false, reason: 'tmux-mode' },
+        at: now(),
+      };
+      log(`[live-bridge] Live su ${snap.hostCell} in modalita' tmux (engine ${engine || 'sconosciuto'})`);
+      return out;
+    }
+
+    let started;
+    try {
+      started = await startThreadOnControlSocket({
+        socketPath: cfg.liveBridgeSocketPath,
+        cwd: cell.cwd,
+        developerInstructions: prompt.applied ? prompt.text : undefined,
+        timeoutMs: cfg.liveBridgeTimeoutMs,
+        WebSocket,
+        log,
+      });
+    } catch (e) {
+      const reason = e && e.code === 'ETIMEOUT' ? 'bridge-timeout' : 'bridge-socket-failed';
+      log(`[live-bridge] thread ponte NON creata (${reason}): ${e.message}`);
+      return none(reason, { cell: snap.hostCell, detail: String(e.message) });
+    }
+
+    const { text, ...promptEcho } = prompt; // il testo del prompt non viaggia in risposta
+    const out = {
+      mode: 'native', cell: snap.hostCell, engine,
+      threadId: started.threadId, cwd: started.cwd,
+      prompt: promptEcho,
+      socketPath: cfg.liveBridgeSocketPath,
+      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})`})`);
+    return out;
+  }
+
+  return { resolveForLive, readCellPrompt: (cellId) => { const { text, ...rest } = readCellPrompt(root, cellId); return rest; } };
+}
+
+let cachedVersion = null;
+function bridgeVersion() {
+  if (cachedVersion) return cachedVersion;
+  try {
+    cachedVersion = require('../../package.json').version || '0';
+  } catch (_) {
+    cachedVersion = '0';
+  }
+  return cachedVersion;
+}
+
+module.exports = { createLiveBridge, readCellPrompt, startThreadOnControlSocket, CLIENT_NAME };