@mmmbuto/nexuscrew 0.9.40 → 0.9.41

package/lib/fleet/managed.js

@@ -5,6 +5,7 @@
 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');
@@ -1601,15 +1602,113 @@ 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.
+//
+// Solo il client `claude` ha questi eventi. Gli altri motori (codex-vl, 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;
+  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];
+  }
+  return { hooks, dirSessione };
+}
+
+// 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 +1842,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 +2311,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 +2465,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,6 +2488,12 @@ 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') {
     if (profile.localProvider) args.push('--oss', '--local-provider', profile.localProvider);
@@ -2599,14 +2793,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 +2837,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,
+};

package/lib/fleet/prompt-delivery.js

@@ -190,8 +190,9 @@ async function deliverBootstrapPrompt(opts = {}) {
   const readyWaitMs = clampInt(opts.readyWaitMs, 15000, 0, 120000);
   const pollMs = clampInt(opts.pollMs, 400, 50, 5000);
   const settleMs = clampInt(opts.settleMs, 150, 0, 5000);
-  const done = (delivered, state, notReady, attempts) => ({
+  const done = (delivered, state, notReady, attempts, mcp) => ({
     delivered, state, notReady, attempts, reason: state,
+    ...(mcp ? { mcp } : {}),
   });
   if (!promptCharsOk(prompt)) return done(false, 'prompt-rejected', '', 0);
 
@@ -217,6 +218,25 @@ async function deliverBootstrapPrompt(opts = {}) {
     await sleepImpl(pollMs);
   }
 
+  // (1b) Gate readiness MCP opzionale (solo claude.*): la mcpWait e'
+  // fornita dal supervisore, con deadline ASSOLUTA composta sullo stesso
+  // orologio del launch (tetto MCP dal budget approvato, mai un budget nuovo a
+  // valle). Il composer pronto resta SEMPRE obbligatorio: qui si arriva solo
+  // col pane ready. A budget esaurito senza MCP pronti la consegna prosegue
+  // come AVVIO DEGRADATO VISIBILE: esito submitted/degraded con l'elenco
+  // bounded dei server failed/pending, mai un lancio silenzioso.
+  let mcp = null;
+  if (typeof opts.mcpWait === 'function') {
+    const r = await opts.mcpWait({ isCancelled: cancelled });
+    if (cancelled() || !r || r.cancelled) return done(false, 'cancelled', '', 0);
+    mcp = {
+      state: r.state === 'ready' ? 'ready' : 'degraded',
+      ready: Array.isArray(r.ready) ? r.ready : [],
+      failed: Array.isArray(r.failed) ? r.failed : [],
+      pending: Array.isArray(r.pending) ? r.pending : [],
+    };
+  }
+
   // (2) Consegna AT-MOST-ONCE: un solo paste per generazione. Il retry copre
   // SOLO fallimenti certi pre-paste (resolve/load); dopo qualsiasi tentativo
   // Di paste-buffer non esiste retry automatico.
@@ -239,32 +259,54 @@ async function deliverBootstrapPrompt(opts = {}) {
       if (paneAgain !== stage.paneId) return done(false, 'delivery-unknown', '', attempts);
       if (cancelled()) return done(false, 'delivery-unknown', '', attempts);
       const enter = await exec(tmuxBin, ['send-keys', '-t', stage.paneId, 'Enter'], { env });
-      if (enter.err) return done(false, 'staged-not-submitted', '', attempts);
+      if (enter.err) return done(false, 'staged-not-submitted', '', attempts, mcp);
       // Cancel con Enter appena partito -> la generazione e' morta con un
       // submit in volo: esito incerto (residuo PTY possibile), mai 'submitted'.
       if (cancelled()) return done(false, 'delivery-unknown', '', attempts);
-      return done(true, 'submitted', '', attempts);
+      return done(true, 'submitted', '', attempts, mcp);
     }
     if (stage.stage === 'paste' || stage.stage === 'validate') {
       // Paste tentato (esito incerto) o input rifiutato: zero secondo paste.
-      return done(false, stage.stage === 'validate' ? 'prompt-rejected' : 'delivery-unknown', '', attempts);
+      return done(false, stage.stage === 'validate' ? 'prompt-rejected' : 'delivery-unknown', '', attempts, mcp);
     }
-    if (attempts >= 2) return done(false, 'failed-pre-paste', '', attempts);
+    if (attempts >= 2) return done(false, 'failed-pre-paste', '', attempts, mcp);
     // Fallimento certo PRE-paste: un solo retry, readiness riverificata prima.
     await sleepImpl(pollMs);
     if (cancelled()) return done(false, 'cancelled', '', attempts);
     const text = await capture();
     const again = text === null ? 'unknown' : classifyPane(text, client);
-    if (again !== 'ready') return done(false, 'failed-pre-paste', '', attempts);
+    if (again !== 'ready') return done(false, 'failed-pre-paste', '', attempts, mcp);
   }
 }
 
 // WaitDeliveryReport(tmuxBin, target, opts) -> delivery-like null.
 // Il launcher supervisionato (cell-exec) e' l'UNICO owner della consegna per
-// TUTTE le generazioni degli engine Kimi e pubblica l'esito bounded sull'
-// opzione tmux di pane @nc_delivery ('<state>' o '<state>:<notReady>', solo
-// enum chiusi; muore col pane, nessuno state file). up() la legge con attesa
-// bounded: niente paste dal runtime, niente doppio writer cross-generation.
+// TUTTE le generazioni degli engine Kimi e claude.* e pubblica l'esito bounded
+// sull'opzione tmux di pane @nc_delivery ('<state>' / '<state>:<notReady>' /
+// '<state>:<notReady>:mcp<state>' dal 0.9.41, solo enum chiusi; muore col
+// pane, nessuno state file). Con degrado MCP l'elenco bounded dei server
+// failed/pending viaggia su @nc_mcp_list ('failed=a,b|pending=c', nomi
+// validati). up() la legge con attesa bounded: niente paste dal runtime,
+// niente doppio writer cross-generation.
+const MCP_REPORT_STATES = Object.freeze(['ready', 'degraded']);
+const MCP_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+function parseMcpListOption(raw) {
+  const out = { failed: [], pending: [] };
+  const text = typeof raw === 'string' ? raw.trim() : '';
+  if (!text) return out;
+  for (const part of text.split('|')) {
+    const eq = part.indexOf('=');
+    if (eq <= 0) continue;
+    const kind = part.slice(0, eq);
+    if (kind !== 'failed' && kind !== 'pending') continue;
+    for (const nome of part.slice(eq + 1).split(',')) {
+      if (nome && MCP_NAME_RE.test(nome) && !out[kind].includes(nome)) out[kind].push(nome);
+    }
+  }
+  return out;
+}
+
 async function waitDeliveryReport(tmuxBin, target, { env, exec, sleepImpl, nowImpl, timeoutMs, pollMs } = {}) {
   const run = exec || tmuxExec;
   const sleepFn = sleepImpl || sleep;
@@ -277,13 +319,24 @@ async function waitDeliveryReport(tmuxBin, target, { env, exec, sleepImpl, nowIm
       { env, timeoutMs: 2000 });
     const raw = r.err ? '' : r.stdout.trim();
     if (raw) {
-      const [state, notReady = ''] = raw.split(':');
+      const [state, notReady = '', mcpTag = ''] = raw.split(':');
       if (!DELIVERY_STATES.includes(state)) return null;   // valore non bounded: mai fidarsi
       const kind = PANE_STATES.includes(notReady) ? notReady : '';
+      const mcpState = mcpTag.startsWith('mcp') && MCP_REPORT_STATES.includes(mcpTag.slice(3))
+        ? mcpTag.slice(3) : '';
+      let mcp = null;
+      if (mcpState) {
+        const r2 = await run(tmuxBin,
+          ['display-message', '-p', '-t', target, '#{@nc_mcp_list}'],
+          { env, timeoutMs: 2000 });
+        const { failed, pending } = parseMcpListOption(r2.err ? '' : r2.stdout);
+        mcp = { state: mcpState, ready: [], failed, pending };
+      }
       return {
         delivered: state === 'submitted',
         state, notReady: state === 'skipped-not-ready' ? kind : '',
         attempts: 0, reason: state,
+        ...(mcp ? { mcp } : {}),
       };
     }
     if (now() >= deadline) return null;
@@ -318,6 +371,6 @@ function actionRequiredFor(client, provider, delivery) {
 }
 
 module.exports = {
-  PANE_STATES, DELIVERY_STATES, ACTION_CODES, RECOVERY_SLUGS,
+  PANE_STATES, DELIVERY_STATES, ACTION_CODES, RECOVERY_SLUGS, MCP_REPORT_STATES, parseMcpListOption,
   classifyPane, deliverBootstrapPrompt, waitDeliveryReport, actionRequiredFor, vlPaneReadiness,
 };