@mmmbuto/nexuscrew 0.9.40 → 0.9.42

package/lib/fleet/cell-exec.js

@@ -8,6 +8,7 @@ const net = require('node:net');
 const path = require('node:path');
 const { spawn } = require('node:child_process');
 const { MAX_PAYLOAD } = require('./launch-broker.js');
+const { scriviStato, scriviGenerazione, AVVIO, USCITA } = require('../files/activity.js');
 const {
   validDaemonChallenge, validVerifyExpected, identityErrorCode,
   IDENTITY_FRAME_LIMIT, IDENTITY_TIMEOUT_MS,
@@ -71,17 +72,37 @@ function promptCharsOk(prompt) {
   return true;
 }
 
+// Gate readiness MCP nel payload. I nomi attesi sono quelli del file
+// cell-mcp materializzato (qualsiasi stringa safe <=64: la charset stretta
+// vale solo sui valori che finiscono nell'opzione pane @nc_mcp_list).
+function validMcpReadiness(value) {
+  if (value === undefined) return true;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  if (Object.keys(value).some((key) => !['cwd', 'expectedServers', 'budgetMs', 'pollMs', 'cacheRoot'].includes(key))) return false;
+  return typeof value.cwd === 'string' && value.cwd.length > 0 && value.cwd.length <= 4096
+    && !/[\0\r\n]/.test(value.cwd)
+    && Array.isArray(value.expectedServers) && value.expectedServers.length > 0
+    && value.expectedServers.length <= 64
+    && value.expectedServers.every((n) => typeof n === 'string' && n.length >= 1
+      && n.length <= 64 && !/[\0\r\n]/.test(n))
+    && (value.budgetMs === undefined || validInteger(value.budgetMs, 0, 120000))
+    && (value.pollMs === undefined || validInteger(value.pollMs, 50, 5000))
+    && (value.cacheRoot === undefined || (typeof value.cacheRoot === 'string'
+      && value.cacheRoot.length > 0 && value.cacheRoot.length <= 4096 && !/[\0\r\n]/.test(value.cacheRoot)));
+}
+
 function validRestartPrompt(value) {
   if (value === undefined) return true;
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  if (Object.keys(value).some((key) => !['tmuxBin', 'tmuxSession', 'prompt', 'readyMs', 'client', 'readyWaitMs'].includes(key))) return false;
+  if (Object.keys(value).some((key) => !['tmuxBin', 'tmuxSession', 'prompt', 'readyMs', 'client', 'readyWaitMs', 'mcpReadiness'].includes(key))) return false;
   return typeof value.tmuxBin === 'string' && value.tmuxBin.length > 0 && value.tmuxBin.length <= 4096
     && !/[\0\r\n]/.test(value.tmuxBin)
     && typeof value.tmuxSession === 'string' && /^[\w.@%:+-]{1,128}$/.test(value.tmuxSession)
     && promptCharsOk(value.prompt)
     && (value.readyMs === undefined || validInteger(value.readyMs, 0, 30000))
     && (value.client === undefined || value.client === '' || value.client === 'kimi' || value.client === 'claude')
-    && (value.readyWaitMs === undefined || validInteger(value.readyWaitMs, 0, 120000));
+    && (value.readyWaitMs === undefined || validInteger(value.readyWaitMs, 0, 120000))
+    && (value.mcpReadiness === undefined || validMcpReadiness(value.mcpReadiness));
 }
 
 function validIdentity(value) {
@@ -109,9 +130,24 @@ function validLease(value) {
     && typeof value.stablePath === 'string' && value.stablePath.length > 0 && value.stablePath.length <= 4096;
 }
 
+// Canale di attivita' della cella: dove il supervisore deve dichiarare l'uscita
+// del client, e con quale generazione. Presente SOLO quando il launcher ha
+// davvero iniettato gli hook (managed.js pubblica la generazione prima di
+// costruire gli argv): senza canale non c'e' niente da invalidare, e un payload
+// senza il campo conserva il comportamento di prima.
+function validActivity(value) {
+  if (value === undefined) return true;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  if (Object.keys(value).some((key) => !['dir', 'generation'].includes(key))) return false;
+  return typeof value.dir === 'string' && value.dir.length > 0 && value.dir.length <= 4096
+    && !/[\0\r\n]/.test(value.dir)
+    && typeof value.generation === 'string' && value.generation.length > 0 && value.generation.length <= 128
+    && !/[\0\r\n]/.test(value.generation);
+}
+
 function validPayload(payload) {
   if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return false;
-  if (Object.keys(payload).some((key) => !['command', 'args', 'env', 'supervise', 'restartPrompt', 'lease', 'identity', 'identityChannel'].includes(key))) return false;
+  if (Object.keys(payload).some((key) => !['command', 'args', 'env', 'supervise', 'restartPrompt', 'lease', 'identity', 'identityChannel', 'activity'].includes(key))) return false;
   if (typeof payload.command !== 'string' || !payload.command || !Array.isArray(payload.args)) return false;
   if (!payload.env || typeof payload.env !== 'object' || Array.isArray(payload.env)) return false;
   // Il launcher decide se il canale identita' esiste (managed.js) e lo dichiara
@@ -124,6 +160,7 @@ function validPayload(payload) {
     && validSupervise(payload.supervise)
     && validRestartPrompt(payload.restartPrompt)
     && validLease(payload.lease)
+    && validActivity(payload.activity)
     && validIdentity(payload.identity);
 }
 
@@ -428,10 +465,36 @@ function waitChild(child) {
 // post-paste incerto (delivery-unknown / staged-not-submitted) — il main loop
 // NON auto-restarta in quel caso (leftover bytes potenzialmente residui nel PTY del
 // pane riusato; fermo bounded + restart operatore).
+// Gate readiness MCP per le claude.* (config.mcpReadiness dal payload).
+// La deadline e' COMPOSTA sullo stesso orologio del launch (notBeforeMs =
+// avvio della GENERAZIONE corrente, mai handshake di una generazione
+// precedente; budgetMs dal tetto approvato) e la cancellazione ferma il polling
+// prima del respawn (isCancelled valutato ad ogni poll dalla deliver).
+function buildMcpWait(config, seams) {
+  const mr = config && config.mcpReadiness;
+  if (!mr || !Array.isArray(mr.expectedServers) || mr.expectedServers.length === 0) return null;
+  const now = seams.nowImpl || Date.now;
+  const startedAt = now();
+  const budget = Math.max(0, Number(mr.budgetMs) || 20000);
+  const waitImpl = seams.waitMcpReadiness || require('./mcp-cache-readiness.js').waitMcpReadiness;
+  return async ({ isCancelled }) => waitImpl({
+    params: { cacheRoot: mr.cacheRoot, cwd: mr.cwd, expectedServers: mr.expectedServers, notBeforeMs: startedAt },
+    deadlineMs: startedAt + budget,
+    pollMs: mr.pollMs || 500,
+    sleepImpl: seams.sleepImpl,
+    nowImpl: seams.nowImpl,
+    isCancelled,
+  });
+}
+
+const MCP_DELIVERY_STATES = ['ready', 'degraded'];
+const MCP_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
 function startGenerationPrompt(config, generation, childState, seams = {}) {
   if (!config) return null;
   const classified = config.client === 'kimi' || config.client === 'claude';
   if (!classified && generation === 0) return null;  // legacy: gen0 resta al runtime
+  const mcpWait = buildMcpWait(config, seams);
   const setTimer = seams.setTimeout || setTimeout;
   const clearTimer = seams.clearTimeout || clearTimeout;
   const runTmux = seams.tmuxExec || ((bin, args, opts = {}) => new Promise((resolve) => {
@@ -444,6 +507,19 @@ function startGenerationPrompt(config, generation, childState, seams = {}) {
     try { await runTmux(config.tmuxBin, ['set-option', '-p', '-t', paneTarget, '@nc_delivery', value], {}); }
     catch (_) { /* best-effort: il report timeout di up() resta onesto */ }
   };
+  // Elenco bounded dei server non pronti su @nc_mcp_list (solo nomi
+  // validati e cap 16 per classe; muore col pane come @nc_delivery).
+  const markMcpList = async (mcp) => {
+    if (!classified || !mcp) return;
+    const valida = (arr) => (Array.isArray(arr) ? arr : [])
+      .filter((n) => typeof n === 'string' && MCP_NAME_RE.test(n)).slice(0, 16).sort();
+    const f = valida(mcp.failed);
+    const p = valida(mcp.pending);
+    if (!f.length && !p.length) return;
+    const value = `${f.length ? `failed=${f.join(',')}` : ''}${f.length && p.length ? '|' : ''}${p.length ? `pending=${p.join(',')}` : ''}`;
+    try { await runTmux(config.tmuxBin, ['set-option', '-p', '-t', paneTarget, '@nc_mcp_list', value], {}); }
+    catch (_) { /* best-effort come @nc_delivery */ }
+  };
   let timer = null; let cancelled = false;
   let settledDone = false; let settleResolve = null;
   const settled = new Promise((resolve) => { settleResolve = resolve; });
@@ -470,6 +546,7 @@ function startGenerationPrompt(config, generation, childState, seams = {}) {
             paneTarget: process.env.TMUX_PANE || undefined,
             readyWaitMs: config.readyWaitMs,
             isCancelled,
+            ...(mcpWait ? { mcpWait } : {}),
           });
           const state = result && typeof result.state === 'string' ? result.state : '';
           const uncertain = state === 'delivery-unknown' || state === 'staged-not-submitted';
@@ -480,7 +557,10 @@ function startGenerationPrompt(config, generation, childState, seams = {}) {
           }
           if (state) {
             const kind = state === 'skipped-not-ready' && result.notReady ? `:${result.notReady}` : '';
-            await markDelivery(`${state}${kind}`);
+            const mcpState = result && result.mcp && MCP_DELIVERY_STATES.includes(result.mcp.state)
+              ? `:mcp${result.mcp.state}` : '';
+            await markDelivery(`${state}${kind}${mcpState}`);
+            if (mcpState) await markMcpList(result.mcp);
           }
           // L'esito post-paste incerto va conservato ANCHE se il child
           // era vivo al ritorno di deliver: i byte possono restare nel PTY del
@@ -527,6 +607,20 @@ async function main(argv = process.argv.slice(2), seams = {}) {
   const sleep = seams.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   const proc = seams.process || process;
   const writeError = seams.writeError || seams.stderrWrite || ((message) => process.stderr.write(message));
+  const activity = payload.activity || null;
+  // Uscita del client: il supervisore DICHIARA che il processo che pubblicava lo
+  // stato non c'e' piu'. Serve perche' il riavvio avviene DENTRO lo stesso
+  // lancio (loop sotto): `activity.gen` non cambia, quindi la generazione non
+  // puo' accorgersi che il client precedente e' morto. Senza questa riga uno
+  // `Stop` dell'ultimo turno resterebbe «ferma» per tutto il backoff — e per
+  // sempre, ora che «ferma» non scade — mentre il client e' morto e il prossimo
+  // non e' pronto. Il lettore mappa l'evento a null: «non verificato».
+  const dichiaraUscita = () => {
+    if (!activity) return;
+    if (scriviStato(activity.dir, { evento: USCITA, generazione: activity.generation, ora: now() }) !== true) {
+      writeError('nexuscrew cell: uscita del client non registrata nello stato di attivita\n');
+    }
+  };
   // Il canale identita' nasce SOLO se il launcher lo ha deciso: la stessa
   // risoluzione che decide CODEX_APP_SERVER_IDENTITY_REQUIRED in managed.js
   // viaggia nel payload come `identityChannel`. Derivarlo qui (aggiungere
@@ -616,6 +710,55 @@ async function main(argv = process.argv.slice(2), seams = {}) {
     for (const [signal, handler] of handlers) proc.off?.(signal, handler);
   };
 
+  // LA GENERAZIONE SI SCRIVE QUI, E SOLO QUI.
+  //
+  // Questo processo gira DENTRO la sessione tmux appena creata: chi perde la
+  // corsa sulla new-session non arriva mai a un cell-exec e quindi non scrive
+  // niente. Scriverla prima (nella risoluzione) significava scriverla anche per
+  // il perdente: sul disco restava la generazione di chi non aveva lanciato
+  // nulla, mentre gli hook del vincitore portavano la loro — e ogni suo evento
+  // veniva scartato al lettore, cioe' «non verificato» su una cella che
+  // lavorava.
+  //
+  // Prima del primo spawn, non dentro il ciclo: la generazione identifica il
+  // LANCIO, e i riavvii interni del client (il ciclo sotto) restano lo stesso
+  // lancio. Il client parte DOPO questa scrittura: mai un hook che scrive una
+  // generazione che non e' ancora su disco.
+  if (activity) {
+    // (1) INVALIDA lo stato lasciato dal client precedente, PRIMA di pubblicare
+    // la generazione. Un evento di lancio porta la generazione nuova e il
+    // lettore lo mappa a null: senza, un «ferma» dell'ultimo turno del client
+    // precedente sopravviverebbe al lancio — e con «ferma» che non scade
+    // resterebbe vero finche' un hook non lo rinnova, cioe' per sempre su una
+    // cella appena partita. Scrivo prima della generazione di proposito:
+    // l'invalidazione non deve dipendere dalla pubblicazione riuscita.
+    if (scriviStato(activity.dir, {
+      evento: AVVIO, generazione: activity.generation, ora: now(),
+    }) !== true) {
+      // LIMITE DICHIARATO (accettato come tale, non un percorso normale): se la
+      // directory e' diventata non scrivibile fra due lanci, QUI non si scrive
+      // niente e lo stato che la UI mostra puo' essere QUELLO DEL LANCIO
+      // PRECEDENTE — un «ferma» dell'ultimo turno di un client che non c'e'
+      // piu'. Il lettore non puo' accorgersene: la generazione su disco e'
+      // ancora la vecchia, e gli eventi nuovi non arrivano finche' un hook non
+      // scrive. E' un guasto del filesystem durante la vita della cella (la
+      // directory e' stata resa non scrivibile), non un esito che il codice
+      // possa riparare da qui: si dichiara nel log, con la conseguenza.
+      writeError("nexuscrew cell: stato di attivita' precedente non invalidato (directory non scrivibile); "
+        + "lo stato mostrato puo' essere quello del lancio precedente\n");
+    }
+    // (2) PUBBLICA la generazione, e con essa il segno che questo supervisore
+    // garantisce l'evento di uscita: e' quel segno a permettere la non scadenza
+    // di «ferma»/«interrotta» nel lettore.
+    if (scriviGenerazione(activity.dir, activity.generation, { uscitaGarantita: true }) !== true) {
+      // Scrittura fallita: si avvia lo stesso, e lo si dichiara. Il client
+      // scrivera' eventi con una generazione che non e' quella su disco, quindi
+      // verranno scartati e la cella risultera' «non verificato» — l'esito
+      // sicuro, mai «ferma» senza fondamento.
+      writeError("nexuscrew cell: generazione di attivita' non pubblicata, stato non verificabile\n");
+    }
+  }
+
   let delayMs = supervise.restartDelayMs;
   let rapid = [];
   try {
@@ -719,6 +862,11 @@ async function main(argv = process.argv.slice(2), seams = {}) {
       childState.exited = true;
       closeIdentityChannel();
       current = null;
+      // Il client non c'e' piu': QUALUNQUE sia la causa (uscita normale, segnale,
+      // errore di spawn, stop dell'operatore) lo stato pubblicato non e' piu'
+      // verificabile. Prima di ogni return del supervisore, cosi' nessuna delle
+      // uscite resta con lo stato del client morto.
+      dichiaraUscita();
       // : la generazione e' finita. Cancella la delivery in volo e ATTESA
       // Del suo termine PRIMA di qualunque nuovo spawn.: se l'esito e' un
       // post-paste incerto (delivery-unknown / staged-not-submitted) i byte del

package/lib/fleet/codex-hooks.js

@@ -0,0 +1,253 @@
+'use strict';
+// Canale di attivita' per le celle codex e codex-vl.
+//
+// Perche' esiste: le celle Claude pubblicano il proprio stato di turno con gli
+// hook di Claude Code (bin/nc-activity-hook.js, iniettato via --settings). Gli
+// engine codex non hanno quel meccanismo, quindi fino a oggi la UI le mostrava
+// «non verificate» — che era la verita', ma anche un'informazione che si poteva
+// avere. Codex ha un sistema di hook proprio, con una differenza che conta:
+// un hook iniettato da riga di comando NON e' fidato finche' il suo hash non
+// compare in `hooks.state`, altrimenti il client apre un dialogo di revisione e
+// non lo esegue.
+//
+// Questo modulo costruisce i due pezzi che servono, e nient'altro:
+//  1. gli argomenti `-c hooks.<Evento>=[...]` che DEFINISCONO l'hook;
+//  2. gli argomenti `-c hooks.state={...}` che lo FIDANO, con l'hash che il
+//     client si aspetta di trovare.
+//
+// L'hash non e' lo sha256 del testo del comando: e' lo sha256 del JSON CANONICO
+// di un'identita' normalizzata (evento + handler normalizzato). Replicato da
+// codex-rs/hooks/src/engine/discovery.rs (`hook_hash`) e
+// codex-rs/config/src/fingerprint.rs (`version_for_toml`).
+//
+// La forma `-c hooks.state.<chiave>.trusted_hash=...` NON funziona: il parser
+// di `-c` spezza il path sui punti (codex-rs/config/src/overrides.rs) e la
+// chiave dell'hook ne contiene. Percio' `hooks.state` si passa come TABELLA
+// inline. Verificato in una prova isolata su TUI reale, su entrambe le
+// versioni in uso.
+
+const crypto = require('node:crypto');
+const { termuxRuntimePaths } = require('../runtime/env.js');
+
+// Etichette usate nelle chiavi di stato — codex-rs/hooks/src/lib.rs,
+// `hook_event_key_label`. Solo gli eventi che iniettiamo.
+const ETICHETTA_EVENTO = Object.freeze({
+  PreToolUse: 'pre_tool_use',
+  PostToolUse: 'post_tool_use',
+  SessionStart: 'session_start',
+  SessionEnd: 'session_end',
+  UserPromptSubmit: 'user_prompt_submit',
+  Stop: 'stop',
+  Interrupt: 'interrupt',
+});
+
+// Timeout normalizzato — codex-rs/hooks/src/engine/discovery.rs,
+// `normalize_command_hook`: dieci minuti per tutti, UN SECONDO per SessionEnd e
+// Interrupt (che hanno anche un tetto di tre). Il valore entra nell'hash,
+// quindi sbagliarlo qui farebbe ricomparire il dialogo di revisione.
+const TIMEOUT_STANDARD_SEC = 600;
+const TIMEOUT_FINE_SEC = 1;
+
+// La fonte sintetica da cui il client crede che l'hook provenga: e' il layer
+// `SessionFlags`, cioe' proprio cio' che passiamo con `-c`
+// (discovery.rs:402-422).
+const KEY_SOURCE_SESSION_FLAGS = '/<session-flags>/config.toml';
+
+function etichetta(evento) {
+  const label = ETICHETTA_EVENTO[evento];
+  if (!label) throw new Error(`evento hook non gestito: ${evento}`);
+  return label;
+}
+
+function timeoutPerEvento(evento) {
+  return evento === 'SessionEnd' || evento === 'Interrupt'
+    ? TIMEOUT_FINE_SEC
+    : TIMEOUT_STANDARD_SEC;
+}
+
+// Riordina le chiavi in modo ricorsivo: `version_for_toml` serializza il JSON
+// CANONICO, e due identita' con le stesse chiavi in ordine diverso devono dare
+// lo stesso hash.
+function ordinaChiavi(valore) {
+  if (Array.isArray(valore)) return valore.map(ordinaChiavi);
+  if (valore && typeof valore === 'object') {
+    const out = {};
+    for (const chiave of Object.keys(valore).sort()) out[chiave] = ordinaChiavi(valore[chiave]);
+    return out;
+  }
+  return valore;
+}
+
+function jsonCanonico(valore) {
+  return JSON.stringify(ordinaChiavi(valore));
+}
+
+/**
+ * Hash atteso da codex per questo handler su questo evento.
+ * Replica `hook_hash` -> `version_for_toml`.
+ */
+function hashHook(evento, comando) {
+  const identita = {
+    event_name: etichetta(evento),
+    hooks: [{
+      async: false,
+      command: comando,
+      timeout: timeoutPerEvento(evento),
+      type: 'command',
+    }],
+  };
+  const digest = crypto.createHash('sha256').update(jsonCanonico(identita), 'utf8').digest('hex');
+  return `sha256:${digest}`;
+}
+
+/** Chiave dello stato per un handler: `hook_key` (hooks/src/lib.rs). */
+function chiaveHook(evento, gruppo = 0, handler = 0) {
+  return `${KEY_SOURCE_SESSION_FLAGS}:${etichetta(evento)}:${gruppo}:${handler}`;
+}
+
+// Stringa TOML. I valori qui sono percorsi e comandi unix, senza backslash:
+// JSON.stringify produce una basic string corretta per questi contenuti.
+function tomlString(valore) {
+  return JSON.stringify(String(valore));
+}
+
+/** Definizione di UN hook: `hooks.<Evento>=[{hooks=[{type,command}]}]`. */
+function definizioneHook(evento, comando) {
+  return `hooks.${evento}=[{hooks=[{type="command",command=${tomlString(comando)}}]}]`;
+}
+
+/** `hooks.state` come tabella inline con un trusted_hash per chiave. */
+function tabellaStato(voci) {
+  const parti = voci.map(({ chiave, hash }) => `${tomlString(chiave)}={trusted_hash=${tomlString(hash)}}`);
+  return `hooks.state={${parti.join(',')}}`;
+}
+
+/**
+ * Argomenti da appendere alla riga di lancio di una cella codex/codex-vl.
+ * `comandoPerEvento(evento)` ritorna il comando dell'hook per quell'evento.
+ * Ritorna [] se non c'e' niente da iniettare.
+ */
+function argomentiHookCodex(eventi, comandoPerEvento) {
+  if (!Array.isArray(eventi) || eventi.length === 0) return [];
+  const args = [];
+  const voci = [];
+  for (const evento of eventi) {
+    const comando = comandoPerEvento(evento);
+    if (!comando) continue;
+    args.push('-c', definizioneHook(evento, comando));
+    voci.push({ chiave: chiaveHook(evento), hash: hashHook(evento, comando) });
+  }
+  if (voci.length === 0) return [];
+  args.push('-c', tabellaStato(voci));
+  return args;
+}
+
+// ── Guardia di versione ────────────────────────────────────────────────
+//
+// L'hash dipende dalla normalizzazione, dalla serializzazione e dal source
+// path sintetico di UNA versione di codex. Se il binario cambia quelle regole,
+// l'hash non combacia piu', il client apre il dialogo «Hooks need review» e la
+// cella resta BLOCCATA su una domanda che nessuno vede. Il costo di sbagliare
+// non e' «hook che non parte»: e' una cella che non lavora.
+//
+// Quindi si inietta SOLO su versioni effettivamente provate, e su ogni altra
+// non si inietta niente: la cella torna «non verificato» come oggi, che e' il
+// comportamento di prima — un degrado dichiarato, non un guasto introdotto.
+const VERSIONI_PROVATE = Object.freeze({
+  codex: ['0.156.1'],
+  'codex-vl': ['0.155.1'],
+});
+
+// Probe della versione, con lo stesso seam del ramo vl (cfg.vlVersionProbe):
+// i test non devono dipendere da un binario vero. Ritorna l'output GREZZO.
+// `binary` e' il percorso RISOLTO del binario della cella, non il nome del
+// client: si esegue quello, senza shell e con un tetto di tempo breve.
+function versionOutput(binary, cfg) {
+  const probe = cfg && typeof cfg.codexVersionProbe === 'function' ? cfg.codexVersionProbe : null;
+  if (probe) {
+    const out = probe(binary);
+    return out === null || out === undefined ? null : String(out);
+  }
+  const { spawnSync } = require('node:child_process');
+  const r = spawnSync(binary, ['--version'], { encoding: 'utf8', timeout: 3000, shell: false });
+  if (r.error || r.status !== 0) return null;
+  return `${r.stdout || ''}${r.stderr || ''}`;
+}
+
+/**
+ * Si puo' iniettare su questo binario? Ritorna { ok, versione } oppure
+ * { ok: false, reason } — il motivo e' per la riga di log, mai per l'utente.
+ * `client` sceglie l'elenco delle versioni provate; `binary` e' cio' che si
+ * esegue davvero. Sono due cose diverse: se coincidono e' una coincidenza.
+ */
+function gateVersione(client, binary, cfg) {
+  const ammesse = VERSIONI_PROVATE[client];
+  if (!ammesse) return { ok: false, reason: `client ${client} non gestito dal canale hook` };
+  if (!binary) {
+    return { ok: false, reason: `binario di ${client} non risolto sul nodo: nessun hook iniettato` };
+  }
+  const out = versionOutput(binary, cfg);
+  if (out === null) {
+    return { ok: false, reason: `versione di ${client} non determinabile (${binary} --version non risponde): nessun hook iniettato` };
+  }
+  const m = out.match(/(\d+\.\d+\.\d+)/);
+  if (!m) {
+    return { ok: false, reason: `versione di ${client} non riconosciuta da "${String(out).trim().slice(0, 60)}": nessun hook iniettato` };
+  }
+  if (!ammesse.includes(m[1])) {
+    return { ok: false, reason: `versione ${client} ${m[1]} non provata con gli hook (provate: ${ammesse.join(', ')}): nessun hook iniettato` };
+  }
+  return { ok: true, versione: m[1] };
+}
+
+// La chiave di fiducia di questi hook e' Unix: `key_source` e'
+// `/<session-flags>/config.toml` e il comando e' quotato in stile POSIX. Il
+// sorgente di codex sintetizza quella fonte con `C:\` su Windows
+// (`hooks/src/engine/discovery.rs:402-435`), quindi la' la chiave che il
+// client calcola NON coincide con quella che generiamo: si inietterebbe un
+// hook non fidato, cioe' esattamente il dialogo che la guardia esiste per
+// evitare. Finche' non c'e' una prova su Windows, li' non si inietta.
+//
+// Termux e' un caso diverso e piu' stretto: il probe esegue il binario
+// direttamente, mentre il launcher lo lancia tramite Node quando lo shim ha
+// uno shebang senza `/usr/bin/env` (`managed.js:1006-1028`). Il gate
+// fallirebbe chiuso, e una cella «non verificata» senza motivo e' un limite
+// che si dichiara qui invece di lasciarlo scoprire.
+function gatePiattaforma(cfg) {
+  const platform = (cfg && cfg.platform) || process.platform;
+  const env = (cfg && cfg.env) || process.env;
+  const termux = platform === 'android'
+    || termuxRuntimePaths(env, { platform, home: cfg && cfg.home }) !== null;
+  if (termux) {
+    return { ok: false, reason: 'termux: il probe della versione non segue il percorso di lancio' };
+  }
+  if (platform !== 'linux' && platform !== 'darwin') {
+    return { ok: false, reason: `piattaforma ${platform}: chiave di fiducia e quoting degli hook non provati qui` };
+  }
+  return { ok: true };
+}
+
+// Eventi iniettati per una cella codex, nell'ordine in cui il client li emette.
+const EVENTI_CODEX = Object.freeze([
+  'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'Interrupt', 'SessionEnd',
+]);
+
+module.exports = {
+  ETICHETTA_EVENTO,
+  TIMEOUT_STANDARD_SEC,
+  TIMEOUT_FINE_SEC,
+  KEY_SOURCE_SESSION_FLAGS,
+  VERSIONI_PROVATE,
+  EVENTI_CODEX,
+  etichetta,
+  timeoutPerEvento,
+  jsonCanonico,
+  hashHook,
+  chiaveHook,
+  definizioneHook,
+  tabellaStato,
+  argomentiHookCodex,
+  versionOutput,
+  gateVersione,
+  gatePiattaforma,
+};