@mmmbuto/nexuscrew 0.9.40 → 0.9.42

package/lib/fleet/managed.js

@@ -5,10 +5,12 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const toml = require('smol-toml');
 const { execFile } = require('node:child_process');
 const { ENV_KEY_RE } = require('./env-key.js');
 const { termuxRuntimePaths } = require('../runtime/env.js');
 const { readCredentialStore, safePrivateDir } = require('./credentials.js');
+const { argomentiHookCodex, gateVersione, gatePiattaforma, EVENTI_CODEX } = require('./codex-hooks.js');
 
 const OLLAMA_CLOUD_MODELS = Object.freeze([
   'glm-5.2', 'kimi-k2.7-code', 'deepseek-v4-pro', 'minimax-m3',
@@ -1601,15 +1603,127 @@ function knownMcpServerNames(home, cwd) {
 //
 // Forma con l'uguale, come `--mcp-config`: un solo token, cosi' nessun argomento
 // successivo puo' essere inghiottito.
-function cellMcpArgs(home, cell) {
+function cellMcpDeny(home, cell) {
   const voluti = cell && Array.isArray(cell.mcp) ? cell.mcp : null;
-  if (!voluti) return [];
-  if (!voluti.length) return [`--settings=${JSON.stringify({ permissions: { deny: ['mcp__*'] } })}`];
+  if (!voluti) return null;
+  if (!voluti.length) return ['mcp__*'];
   const concessi = new Set(voluti);
-  const deny = [...knownMcpServerNames(home, cell.cwd)]
+  return [...knownMcpServerNames(home, cell.cwd)]
     .filter((nome) => !concessi.has(nome)).sort().map((nome) => `mcp__${nome}`);
-  if (!deny.length) return [];
-  return [`--settings=${JSON.stringify({ permissions: { deny } })}`];
+}
+
+// --- stato attivita' dagli hook ---------------------------------------------
+//
+// Le celle Claude pubblicano il proprio stato di turno con gli hook di Claude
+// Code, invece di lasciarlo dedurre dal titolo del pane — che non lo prova
+// (il glifo `✳` sta sia su una cella al lavoro sia su una ferma).
+//
+// Il canale e' lo STESSO `--settings` che la cella riceve gia' per il deny MCP:
+// un solo token composto, non due sorgenti distinte. Dove quel token oggi non
+// esiste (ramo strict) ne nasce uno che porta SOLO gli hook.
+//
+// Il client `claude` li riceve via `--settings` (sotto). Il client codex e
+// codex-vl li riceve in forma `-c` (lib/fleet/codex-hooks.js), con la stessa
+// matrice evento->stato e lo stesso scrittore — e li riceve SOLO su versioni
+// provate, perche' la fiducia dell'hook dipende dall'hash di quella versione.
+// Gli altri motori (pi, shell) restano senza canale: la UI li mostra «non
+// verificati», che e' cio' che si sa di loro. Non si inventa uno stato che
+// nessuno pubblica.
+
+// Gli eventi REGISTRATI, quelli misurati su 2.1.280 nel Gate A. `StopFailure`
+// non compare perche' su quella versione NON esiste: registrarlo sarebbe una
+// riga che non scatta mai.
+const EVENTI_ATTIVITA = Object.freeze([
+  'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse',
+  'SubagentStop', 'Stop', 'PermissionRequest', 'Notification', 'SessionEnd',
+]);
+
+// La root dei file per-cella. `cfg.filesRoot` c'e' quando la risoluzione arriva
+// dal server (che la porta nella propria cfg); alcuni chiamanti — i test in
+// isolamento — non la passano. In quel caso la si ricava dalla STESSA fonte di
+// configurazione invece di aggiungere un parametro che nessuno passerebbe:
+// `defaults()` e' baseDefaults + env (quindi onora NEXUSCREW_FILES_ROOT) e NON
+// legge il config.json del device, che e' esattamente cio' che serve a un
+// chiamante che non ha una cfg.
+function filesRootDi(cfg) {
+  if (cfg && typeof cfg.filesRoot === 'string' && cfg.filesRoot) return cfg.filesRoot;
+  try {
+    const r = require('../config.js').defaults().filesRoot;
+    return typeof r === 'string' && r ? r : null;
+  } catch (_) { return null; }
+}
+
+// Quoting POSIX: il comando di un hook e' una stringa che il client esegue con
+// la shell, e percorso dello script e directory di sessione possono contenere
+// spazi. Il singolo apice si rappresenta chiudendo, escapando e riaprendo —
+// l'unico modo che funziona anche dentro una stringa gia' quotata.
+function virgolette(valore) {
+  return `'${String(valore).replace(/'/g, "'\\''")}'`;
+}
+
+// Comando di UN hook. `process.execPath` e' il node che sta eseguendo il
+// server: e' lo stesso interprete che deve eseguire lo script, senza dipendere
+// dal PATH della cella.
+function comandoHook(evento, script, dirSessione, generazione) {
+  const parti = [
+    virgolette(process.execPath), virgolette(script),
+    '--event', virgolette(evento), '--dir', virgolette(dirSessione),
+  ];
+  if (generazione) parti.push('--gen', virgolette(generazione));
+  return parti.join(' ');
+}
+
+// Oggetto `hooks` per la settings della cella, oppure null quando non e'
+// iniettabile (cella senza sessione tmux: senza nome non c'e' dove scrivere).
+function cellActivityHooks(cell, cfg) {
+  // Opt-out esplicito. Serve a due cose: un operatore che non vuole hook nella
+  // cella, e il test che confronta gli argomenti di lancio con e senza — un
+  // confronto che gira sulla STESSA strada di codice, non su una copia.
+  if (cfg && cfg.activityHooks === false) return null;
+  if (!cell || typeof cell.tmuxSession !== 'string' || !cell.tmuxSession) return null;
+  const root = filesRootDi(cfg);
+  if (!root) return null;
+  const script = path.join(__dirname, '..', '..', 'bin', 'nc-activity-hook.js');
+  try { if (!fs.statSync(script).isFile()) return null; } catch (_) { return null; }
+  const dirSessione = path.join(root, cell.tmuxSession);
+  const generazione = cfg && typeof cfg.activityGeneration === 'string' && cfg.activityGeneration
+    ? cfg.activityGeneration : null;
+  // QUI NON SI SCRIVE NIENTE SU DISCO. La generazione viaggia negli argv degli
+  // hook e nel payload del broker; a scriverla e' `cell-exec`, che gira DENTRO
+  // la sessione tmux appena creata — quindi solo per il vincitore della
+  // new-session — e lo fa prima di avviare il client (cell-exec.js: la
+  // generazione su disco e' quella del client che gira davvero). Scriverla qui
+  // significava scriverla anche per chi stava per perdere la corsa: sul disco
+  // restava la generazione del perdente, che non e' quella di nessun lancio
+  // vivo, e ogni evento del vincitore veniva scartato al lettore.
+  const hooks = {};
+  for (const evento of EVENTI_ATTIVITA) {
+    const voce = { hooks: [{ type: 'command', command: comandoHook(evento, script, dirSessione, generazione) }] };
+    // `matcher: '*'` SOLO sui due eventi tool: e' la forma MISURATA nel Gate A.
+    // `Notification` viaggia senza matcher di proposito — filtrare per tipo
+    // dalla settings significherebbe affidarsi a una semantica di matcher che
+    // non e' stata misurata, e un matcher sbagliato spegnerebbe in silenzio
+    // l'unico segnale di «attesa permesso». Il filtro per tipo lo fa lo script.
+    if (evento === 'PreToolUse' || evento === 'PostToolUse') voce.matcher = '*';
+    hooks[evento] = [voce];
+  }
+  // `script` e `generazione` escono insieme agli hooks perche' servono anche al
+  // canale codex, che ricompone lo stesso comando in forma `-c`.
+  return { hooks, dirSessione, script, generazione };
+}
+
+// L'argomento `--settings` della cella: deny MCP e hook in UN SOLO oggetto.
+// Due sorgenti distinte sarebbero tecnicamente sicure per il deny (misurato:
+// con due `--settings` vince il deny), ma un oggetto solo e' cio' che si puo'
+// confrontare campo per campo con quello di prima — ed e' il confronto che
+// dimostra che l'unica chiave aggiunta e' `hooks`.
+function cellSettingsArgs(home, cell, attivita) {
+  const deny = cellMcpDeny(home, cell);
+  const out = {};
+  if (deny && deny.length) out.permissions = { deny };
+  if (attivita) out.hooks = attivita.hooks;
+  if (!Object.keys(out).length) return [];
+  return [`--settings=${JSON.stringify(out)}`];
 }
 
 // Definizioni MCP note, per NOME -> definizione (la prima sorgente che dichiara
@@ -1743,48 +1857,132 @@ function readCodexUserToml(codexHome) {
   return '';
 }
 
+// Superficie codex della config utente come TABELLE strutturate. Il parse e'
+// TOML vero (smol-toml), non la regex dei soli nomi di codexSurfaceNames: al
+// writer servono i blocchi completi dei server per copiare il trasporto, e
+// nomi quotati, sottotabelle e valori composti escono corretti. Una config
+// utente presente ma non parseabile e' un errore (fail-closed): si rifiuta il
+// profilo intero invece di emetterne uno che non ridurrebbe nulla.
+function codexSurfaceTables(configToml) {
+  const testo = typeof configToml === 'string' ? configToml : '';
+  if (!testo.trim()) return { servers: new Map(), skills: [] };
+  let doc;
+  try {
+    doc = toml.parse(testo);
+  } catch (e) {
+    const err = new Error(`config utente non parseabile come TOML: ${e.message}`);
+    err.code = 'CODEX_USER_TOML_INVALID';
+    throw err;
+  }
+  const raw = doc.mcp_servers && typeof doc.mcp_servers === 'object' && !Array.isArray(doc.mcp_servers)
+    ? doc.mcp_servers
+    : {};
+  const servers = new Map();
+  for (const [nome, tabella] of Object.entries(raw)) {
+    if (tabella && typeof tabella === 'object' && !Array.isArray(tabella)) servers.set(nome, tabella);
+  }
+  const voci = Array.isArray(doc.skills && doc.skills.config) ? doc.skills.config : [];
+  const skills = [...new Set(voci
+    .filter((s) => s && typeof s === 'object' && typeof s.name === 'string' && s.name)
+    .map((s) => s.name))];
+  return { servers, skills };
+}
+
+// Rami di trasporto MCP e chiavi MINIME che soddisfano la validazione del
+// client: per stdio basta `command`, per streamable_http solo `url`. Per uno
+// SPENTO si copia solo questo: `args`, `env`, `http_headers`,
+// `bearer_token_env_var` e simili non servono a far passare il layer e sono
+// i campi che portano segreti (un token puo stare anche in `args`) — un file
+// derivato e rigenerato non deve duplicarli. Per un on-DEMAND si copia
+// invece la definizione INTEGRALE della tabella base: quel server e
+// concesso, il segreto gli compete, e la copia identica non puo introdurre
+// invalidita' nuove (la base valida resta valida).
+const TRASPORTO_MCP_STDIO = ['command'];
+const TRASPORTO_MCP_HTTP = ['url'];
+
+function ramoTrasporto(tabella) {
+  if (tabella && tabella.command !== undefined) return 'stdio';
+  if (tabella && tabella.url !== undefined) return 'http';
+  const err = new Error('server MCP senza trasporto riconoscibile (command/url) nella config utente');
+  err.code = 'CODEX_MCP_TRANSPORT_UNKNOWN';
+  throw err;
+}
+
+function trasportoMinimo(tabella) {
+  const campi = ramoTrasporto(tabella) === 'stdio' ? TRASPORTO_MCP_STDIO : TRASPORTO_MCP_HTTP;
+  const out = {};
+  for (const k of campi) {
+    if (tabella[k] !== undefined) out[k] = tabella[k];
+  }
+  return out;
+}
+
 function writeCellCodexProfile(cellId, declared, codexHome) {
   const nome = `nexuscrew-${String(cellId).replace(/\./g, '_')}`;
   const target = path.join(codexHome, `${nome}.config.toml`);
   const configToml = readCodexUserToml(codexHome);
-  const { servers, skills } = codexSurfaceNames(configToml);
+  const { servers, skills } = codexSurfaceTables(configToml);
   const mcpConcessi = new Set(declared.mcp || []);
   const ondemand = new Set(declared.ondemand || []);
   const skillConcesse = new Set(declared.skills || []);
-  const righe = [
-    '# Generated by NexusCrew for this cell: reduces (never widens) the surface',
-    '# declared in config.toml, which NexusCrew never modifies.',
-  ];
+  const nomiServer = [...servers.keys()].sort();
+  const profilo = {};
+  // OGNI tabella MCP emessa e' valida ANCHE DA SOLA: il write path
+  // del client (config/batchWrite) valida il layer attivo PRIMA del documento
+  // fuso (config_manager_service.rs: get_active_user_layer -> validate_config),
+  // quindi una tabella ridotta senza trasporto romperebbe il salvataggio.
+  // Copiare il trasporto non avvia gli spenti: restano `enabled = false`, e
+  // il connection manager non li itera (connection_manager.rs). Spento =
+  // minimo che soddisfa la validazione (mai segreti); on-demand = definizione
+  // effettiva del layer base con la sola chiave di differimento sopra.
   if (declared.mcp !== undefined) {
-    for (const s of servers.filter((n) => !mcpConcessi.has(n)).sort()) {
-      righe.push('', `[mcp_servers.${s}]`, 'enabled = false');
+    const tabelle = {};
+    for (const s of nomiServer.filter((n) => !mcpConcessi.has(n))) {
+      tabelle[s] = { ...trasportoMinimo(servers.get(s)), enabled: false };
     }
+    if (Object.keys(tabelle).length) profilo.mcp_servers = tabelle;
   }
   // `omit_tools_from` NON e' una chiave di root: in codex e' un campo della
   // tabella del SINGOLO server (codex-rs/config/src/mcp_types.rs:223/:364) —
   // a root viene ignorato in silenzio e l'on-demand non funzionerebbe mai.
   // Un server on-demand e' CONCESSO ma differito: enabled resta il default e
-  // si scrive solo la chiave di differimento; uno spento (non concesso con
+  // la tabella riproduce la definizione del layer base (valida da sola) con
+  // la sola chiave di differimento sopra. Uno spento (non concesso con
   // `mcp` dichiarata) non prende una seconda tabella: TOML vieta i duplicati
   // e enabled = false resta il volere piu' restrittivo. Nomi ondemand non
   // presenti nella config utente non generano tabelle (ignorati; la vista li
   // segnala).
   if (ondemand.size) {
     const spenti = declared.mcp !== undefined
-      ? new Set(servers.filter((n) => !mcpConcessi.has(n)))
+      ? new Set(nomiServer.filter((n) => !mcpConcessi.has(n)))
       : new Set();
-    for (const s of servers.filter((n) => ondemand.has(n) && !spenti.has(n)).sort()) {
-      righe.push('', `[mcp_servers.${s}]`, 'omit_tools_from = ["direct"]');
+    const tabelle = profilo.mcp_servers || (profilo.mcp_servers = {});
+    for (const s of nomiServer.filter((n) => ondemand.has(n) && !spenti.has(n))) {
+      // Anche l'on-demand deve essere valido da solo: la copia integrale del
+      // layer base contiene il trasporto se il layer base e' valido; se non
+      // ce l'ha, rifiuta invece di emettere una tabella invalida.
+      ramoTrasporto(servers.get(s));
+      tabelle[s] = { ...servers.get(s), omit_tools_from: ['direct'] };
     }
+    if (!Object.keys(tabelle).length) delete profilo.mcp_servers;
   }
   if (declared.skills !== undefined) {
-    for (const s of skills.filter((n) => !skillConcesse.has(n)).sort()) {
-      righe.push('', '[[skills.config]]', `name = "${s}"`, 'enabled = false');
+    const nonConcesse = skills.filter((n) => !skillConcesse.has(n));
+    if (nonConcesse.length) {
+      profilo.skills = { config: nonConcesse.map((name) => ({ name, enabled: false })) };
     }
   }
+  const righe = [
+    '# Generated by NexusCrew for this cell: reduces (never widens) the surface',
+    '# declared in config.toml, which NexusCrew never modifies.',
+    '# MCP transport fields are copied from config.toml: every table here is',
+    '# valid on its own (the client validates this layer standalone on write).',
+  ];
+  const corpo = Object.keys(profilo).length ? toml.stringify(profilo).trimEnd() : '';
+  const testo = corpo ? `${righe.join('\n')}\n\n${corpo}\n` : `${righe.join('\n')}\n`;
   const tmp = path.join(codexHome, `.${nome}.${crypto.randomBytes(6).toString('hex')}.tmp`);
   try {
-    fs.writeFileSync(tmp, `${righe.join('\n')}\n`, { mode: 0o600 });
+    fs.writeFileSync(tmp, testo, { mode: 0o600 });
     fs.chmodSync(tmp, 0o600);
     fs.renameSync(tmp, target);
   } catch (e) {
@@ -2128,6 +2326,9 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
   // I due profili Claude con configurazione privata: perdono gli MCP del file
   // principale e vanno ricollegati (vedi `sharedMcpArgs`).
   let privateProfile = false;
+  // Directory di sessione degli hook di attivita': il launcher ci scrive la
+  // generazione corrente. Null quando gli hook non sono iniettabili.
+  let activityDir = null;
   // Effective permission policy: override PER-CELL PER-ENGINE (remembered) vince sul
   // default dell'engine. Mai si mutationa engine.managed.permissionPolicy (globale).
   // Pi resta sempre 'standard' (lo spec normalized rifiuta gia' unsafe per pi).
@@ -2279,8 +2480,10 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     // l'abbia chiesto.
     const { effectiveCapabilities } = require('./definitions.js');
     const eff = effectiveCapabilities(cell || {}, { capabilityProfiles: cfg.capabilityProfiles || null });
+    const attivita = cellActivityHooks(cell, cfg);
+    if (attivita) activityDir = attivita.dirSessione;
     if (eff.legacy || eff.declared.mcp === undefined) {
-      args.push(...cellMcpArgs(home, cell));
+      args.push(...cellSettingsArgs(home, cell, attivita));
     } else {
       let file;
       try {
@@ -2300,8 +2503,48 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
         return { ok: false, reason: motivo, mcpCellRefused: motivo };
       }
       args.push('--strict-mcp-config', `--mcp-config=${file}`);
+      // Qui il `--settings` NON esisteva: nasce per gli hook e porta SOLO
+      // quelli. Nessun `permissions`: in questo ramo la superficie la chiude
+      // `--strict-mcp-config` con il file per cella, e aggiungere un deny
+      // calcolato per enumerazione cambierebbe cio' che la cella vede — non e'
+      // richiesto e non si fa.
+      if (attivita) args.push(`--settings=${JSON.stringify({ hooks: attivita.hooks })}`);
     }
   } else if (spec.client === 'codex' || spec.client === 'codex-vl') {
+    // Canale di attivita' per le celle codex: gli stessi eventi che le celle
+    // Claude pubblicano via `--settings`, qui come hook `-c` con la fiducia che
+    // il client pretende (senza, apre un dialogo di revisione e la cella resta
+    // ferma su una domanda). Vince SOLO su versioni provate: su ogni altra non
+    // si inietta niente e la cella torna «non verificato» come prima — un
+    // degrado dichiarato, mai un dialogo che blocca il turno.
+    {
+      // `attivita` e' dichiarata nel ramo claude e qui non e' in scope: si
+      // ricalcola. E' pura e non scrive niente su disco: calcola gli stessi
+      // argv (stessa generazione) per il client codex.
+      const attivita = cellActivityHooks(cell, cfg);
+      // Il gate riceve il binario RISOLTO per questa cella (`info.binary`,
+      // lo stesso che finisce in argv a fine funzione), non il nome del
+      // client: col nome si interrogherebbe il PATH del processo, che puo'
+      // essere un eseguibile DIVERSO da quello che la cella lancera'. La
+      // guardia esiste per non far bloccare la cella su un dialogo di
+      // revisione, e una guardia che guarda un altro binario da' il via
+      // libero sbagliato: e' il caso che deve impedire.
+      const piattaforma = gatePiattaforma(cfg);
+      const gate = piattaforma.ok ? gateVersione(spec.client, info.binary, cfg) : piattaforma;
+      if (!gate.ok) {
+        if (typeof cfg.log === 'function') cfg.log(`hook codex non iniettati: ${gate.reason}`);
+      } else if (attivita) {
+        args.push(...argomentiHookCodex(EVENTI_CODEX,
+          (evento) => comandoHook(evento, attivita.script, attivita.dirSessione, attivita.generazione)));
+        // Qui si dichiara che QUESTA cella ha un canale di attivita': e' il
+        // `dir` che fa viaggiare verso il supervisore il dove e il
+        // con-che-generazione dell'evento di uscita (runtime.js) e la
+        // scrittura di `activity.gen` da parte di cell-exec, e senza di esso un
+        // `Stop` dell'ultimo turno sopravviverebbe al riavvio interno del
+        // client.
+        activityDir = attivita.dirSessione;
+      }
+    }
     if (profile.localProvider) args.push('--oss', '--local-provider', profile.localProvider);
     else if (spec.provider === 'openai-api') env.OPENAI_API_KEY = cred.value;
     else if (spec.provider === 'ollama-cloud') {
@@ -2599,14 +2842,15 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
       }
     }
   }
-  // Prompt su argv (0.8.47): SOLO i client che non hanno un percorso classified
-  // delivery. kimi.native e claude.kimi-code usano promptMode 'send-keys' con
-  // deliverBootstrapPrompt (readiness classificata + at-most-once): il prompt
-  // NON deve mai comparire nel loro argv (visibile in ps / perso dietro
-  // consenso/onboarding). Gli altri managed conservano il contratto argv
-  // (finding separato, fuori da questa patch).
-  const promptViaDelivery = spec.client === 'kimi'
-    || (spec.client === 'claude' && spec.provider === 'kimi-code');
+  // Prompt su argv (0.8.47) SOLO per i client senza percorso classified
+  // delivery. Dalla 0.9.41: TUTTE le claude.* passano a consegna
+  // ritardata (kimi.* le avevano dal 0.8.47) — promptMode 'send-keys' con
+  // deliverBootstrapPrompt (readiness classificata + at-most-once + gate
+  // readiness MCP sui log cache del client): il bootstrap NON parte più
+  // prima della handshake MCP e non compare in argv (visibile in ps / perso
+  // dietro consenso/onboarding). vl non ha superficie prompt (file dedicato),
+  // shell e' one-shot/login: nessun posizionale per loro per costruzione.
+  const promptViaDelivery = spec.client === 'kimi' || spec.client === 'claude';
   // vl is a TUI without a prompt surface (`vl [OPTIONS]`, no prompt flag):
   // it NEVER receives the per-cell prompt on argv — it travels in the
   // per-cell file composed by the vl branch (VL_SYSTEM_APPEND_FILE).
@@ -2642,7 +2886,7 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     command = cfg.nodeExecPath || process.execPath;
     args.unshift(info.binary);
   }
-  return { ok: true, info, engine: {
+  return { ok: true, info, activityDir, engine: {
     ...engine, command, args, env,
     promptMode: promptViaDelivery ? 'send-keys' : 'managed-argv', clientBinary: info.binary,
     // Canale identita' (vedi sopra): assente per i client senza REQUIRED, cosi'

package/lib/fleet/mcp-cache-readiness.js

@@ -0,0 +1,154 @@
+'use strict';
+// Readiness MCP per-server dalla cache del client Claude Code.
+//
+// Il client 2.1.280 scrive, per ogni server MCP e per ogni avvio di processo,
+// un log diagnostico in:
+//   ~/.cache/claude-cli-nodejs/<encoded-cwd>/mcp-logs-<server>/<bootUTC>.jsonl
+// con encoded-cwd = ogni non-alfanumerico sostituito da '-', un file jsonl per
+// boot del processo client e `sessionId` in ogni riga. Stati osservati sul
+// 2.1.280 (misurato con 8 probe tmux su sessioni usa-e-getta):
+//   pending: "Starting connection with timeout of 30000ms"
+//   ready:   "Successfully connected (transport: stdio) in <N>ms"
+//   failed:  "Connection failed after <N>ms (CONNECTION_CLOSED): Connection closed"
+//            e/o record {"error": "..."} SENZA campo `debug` (schema variabile).
+//
+// QUESTO E' UN ADATTATORE VERSIONATO su client 2.1.280: il formato e'
+// diagnostica del client, non un contratto. Ogni lettura e' tollerante (righe
+// non-JSON o senza campi noti vengono ignorate, errori di I/O degradano a
+// pending) e il modulo dichiara la versione supportata in
+// ADAPTER_CLIENT_VERSION; un client futuro che cambia formato degrada a
+// pending visibile, mai crash.
+//
+// L'insieme atteso e' quello MATERIALIZZATO della cella (chiavi del file
+// cell-mcp/<cellId>.json): un server non concesso non esiste per il launch
+// (disabled per costruzione, non uno stato di questo adattatore). Il boot
+// corrente e' il file con nome-stamp >= notBeforeMs del launch: i log delle
+// generazioni precedenti non sbloccano mai (nessun handshake vecchio).
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// Versione del client su cui il formato dei log e' stato misurato (probe).
+const ADAPTER_CLIENT_VERSION = '2.1.280';
+
+// Stati bounded per server e per insieme. 'degraded' = insieme non tutti
+// ready ma concluso (almeno un failed/pending scaduto il budget).
+const SERVER_STATES = Object.freeze(['pending', 'ready', 'failed']);
+const SET_STATES = Object.freeze(['pending', 'ready', 'degraded']);
+
+const READY_RE = /Successfully connected/;
+const FAILED_RE = /Connection failed/;
+const BOOT_RE = /Starting connection/;
+
+// '2026-09-22T18:46:09.220Z' -> '2026-09-22T18-46-09-220Z': lo stesso stamp
+// che il client usa per i nomi dei boot file. Ordina lessicograficamente
+// come il tempo.
+function bootStampOf(ms) {
+  return new Date(Number(ms) || 0).toISOString().replace(/[^A-Za-z0-9TZ]/g, '-');
+}
+
+function encodeCwdForCache(cwd) {
+  return String(cwd || '').replace(/[^A-Za-z0-9]/g, '-');
+}
+
+function clampInt(value, dflt, min, max) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return dflt;
+  return Math.max(min, Math.min(max, Math.trunc(n)));
+}
+
+// Stato di UN server nel boot corrente: il file piu' recente con nome-stamp
+// >= notBeforeStamp decide; i boot vecchi non vengono nemmeno letti.
+function readServerState(fsImpl, serverDir, notBeforeStamp) {
+  let names = [];
+  try {
+    names = fsImpl.readdirSync(serverDir)
+      .filter((n) => n.endsWith('.jsonl') && n.slice(0, -6) >= notBeforeStamp)
+      .sort()
+      .reverse();
+  } catch (_) {
+    return 'pending'; // directory assente o illeggibile: server non ancora partito
+  }
+  if (!names.length) return 'pending';
+  let text = '';
+  try {
+    text = fsImpl.readFileSync(path.join(serverDir, names[0]), 'utf8');
+  } catch (_) {
+    return 'pending';
+  }
+  let sawBoot = false;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let rec = null;
+    try {
+      rec = JSON.parse(line);
+    } catch (_) {
+      continue; // riga malformata: ignorata, mai crash su diagnostica
+    }
+    if (!rec || typeof rec !== 'object') continue;
+    const dbg = typeof rec.debug === 'string' ? rec.debug : '';
+    // Le failure usano la chiave `error` senza campo `debug` (misurato 2.1.280).
+    if (!dbg && typeof rec.error === 'string' && rec.error) return 'failed';
+    if (READY_RE.test(dbg)) return 'ready';
+    if (FAILED_RE.test(dbg)) return 'failed';
+    if (BOOT_RE.test(dbg)) sawBoot = true;
+  }
+  return sawBoot ? 'pending' : 'pending';
+}
+
+// Istantanea dell'insieme materializzato: {state, servers, ready, failed,
+// pending, adapterClientVersion}. Con attesa vuota lo stato e' 'ready'
+// (nessun server da aspettare: il gate non deve ritardare la consegna).
+function readinessNow({
+  cacheRoot, cwd, expectedServers, notBeforeMs, fsImpl = fs,
+} = {}) {
+  const root = typeof cacheRoot === 'string' && cacheRoot
+    ? cacheRoot
+    : path.join(os.homedir(), '.cache', 'claude-cli-nodejs');
+  const encoded = encodeCwdForCache(cwd);
+  const notBeforeStamp = bootStampOf(notBeforeMs);
+  const servers = {};
+  const attesi = Array.isArray(expectedServers) ? expectedServers : [];
+  for (const name of attesi) {
+    if (typeof name !== 'string' || !name) continue;
+    servers[name] = readServerState(fsImpl, path.join(root, encoded, `mcp-logs-${name}`), notBeforeStamp);
+  }
+  const ready = Object.keys(servers).filter((k) => servers[k] === 'ready').sort();
+  const failed = Object.keys(servers).filter((k) => servers[k] === 'failed').sort();
+  const pending = Object.keys(servers).filter((k) => servers[k] === 'pending').sort();
+  const state = attesi.length === 0
+    ? 'ready'
+    : (failed.length === 0 && pending.length === 0 ? 'ready'
+      : (pending.length === 0 ? 'degraded' : 'pending'));
+  return { state, servers, ready, failed, pending, adapterClientVersion: ADAPTER_CLIENT_VERSION };
+}
+
+// Attesa bounded dell'insieme: termina su insieme concluso (zero pending),
+// su deadline, o su cancellazione. La DEADLINE e' assoluta e composta dal
+// chiamante (un solo budget composto): `deadlineMs` e' l'epoch del tetto MCP,
+// tipicamente launchStartMs + 20000, che consume lo stesso orologio del
+// composer (readyWaitMs). Ritorna {cancelled:true} oppure l'ultima
+// readinessNow piu' `waited` e `timedOut`.
+async function waitMcpReadiness({
+  params, deadlineMs, pollMs = 500, sleepImpl, nowImpl, isCancelled, fsImpl,
+} = {}) {
+  const sleepFn = sleepImpl || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = nowImpl || Date.now;
+  const deadline = Number(deadlineMs) || 0;
+  const started = now();
+  let last = null;
+  for (;;) {
+    if (typeof isCancelled === 'function' && isCancelled()) {
+      return { cancelled: true };
+    }
+    last = readinessNow({ ...(params || {}), fsImpl: fsImpl || (params && params.fsImpl) });
+    if (last.state !== 'pending') return { ...last, waited: now() - started, timedOut: false };
+    if (now() >= deadline) return { ...last, waited: now() - started, timedOut: true };
+    await sleepFn(clampInt(pollMs, 500, 50, 5000));
+  }
+}
+
+module.exports = {
+  ADAPTER_CLIENT_VERSION, SERVER_STATES, SET_STATES,
+  bootStampOf, encodeCwdForCache, readinessNow, waitMcpReadiness, readServerState,
+};