@mmmbuto/nexuscrew 0.9.30 → 0.9.32

package/frontend/dist/index.html

@@ -11,7 +11,7 @@
   <meta name="apple-mobile-web-app-title" content="NexusCrew" />
   <link rel="manifest" href="/manifest.json" />
   <title>NexusCrew</title>
-  <script type="module" crossorigin src="/assets/index-BbcjoZS0.js"></script>
+  <script type="module" crossorigin src="/assets/index-CH2iAu6y.js"></script>
   <link rel="stylesheet" crossorigin href="/assets/index-DqCfZFGi.css">
 </head>
 <body>

package/frontend/dist/version.json

@@ -1 +1 @@
-{"version":"0.9.30"}
+{"version":"0.9.32"}

package/lib/cli/doctor.js

@@ -393,6 +393,24 @@ function checkTermuxExec(runtimeEnv, opts = {}) {
   };
 }
 
+// «Server assente» e «non ho potuto guardare» sono due cose diverse, e vanno
+// dette diverse. La prima e' uno stato normale — il server non c'e' ancora, la
+// probe si rinvia al primo avvio. La seconda e' un'informazione che manca:
+// collassarla nella prima significa dichiarare sano cio' che non si e'
+// verificato, che e' esattamente il modo in cui un permesso sbagliato resta
+// invisibile. E' la stessa distinzione gia' fatta fra «manca» e «non
+// verificabile» altrove nel prodotto.
+function classifyTmuxProbeCause(error) {
+  const code = String((error && error.code) || '');
+  const message = String((error && error.message) || error || '');
+  if (code === 'ENOENT'
+    || /no server running|no such file or directory|connection refused|no sessions/i.test(message)) {
+    return 'absent';
+  }
+  const cause = (code || message.trim() || 'errore non nominato');
+  return cause.length > 120 ? `${cause.slice(0, 117)}...` : cause;
+}
+
 // Read-only probe of the long-lived tmux server cwd. A server that retained an
 // unlinked runtime directory keeps accepting clients but makes later children
 // fail getcwd(3). Never reports the path itself; only stable state.
@@ -403,8 +421,15 @@ function checkTmuxServerCwd(platform, execImpl, opts = {}) {
   let rawPid = '';
   try {
     rawPid = String(execImpl(opts.tmuxBin || 'tmux', ['display-message', '-p', '#{pid}'], { encoding: 'utf8' }) || '').trim();
-  } catch (_) {
-    return { name: 'tmux server cwd', ok: true, warn: true, detail: 'server tmux non attivo; probe rinviato al primo avvio' };
+  } catch (error) {
+    const cause = classifyTmuxProbeCause(error);
+    if (cause === 'absent') {
+      return { name: 'tmux server cwd', ok: true, warn: true, detail: 'server tmux non attivo; probe rinviato al primo avvio' };
+    }
+    return {
+      name: 'tmux server cwd', ok: false, warn: true,
+      detail: `probe non verificabile: ${cause}`,
+    };
   }
   if (!/^\d+$/.test(rawPid)) {
     return { name: 'tmux server cwd', ok: true, warn: true, detail: 'server tmux non rilevato' };
@@ -435,8 +460,37 @@ function checkTmuxServerTermuxPreload(runtimeEnv, execImpl, opts = {}) {
   let raw = '';
   try {
     raw = String(execImpl(opts.tmuxBin || 'tmux', ['show-environment', '-g', 'LD_PRELOAD'], { encoding: 'utf8' }) || '').trim();
-  } catch (_) {
-    return { name: 'tmux server termux-exec', ok: true, warn: true, detail: 'server tmux non attivo; probe rinviato al primo avvio' };
+  } catch (err) {
+    // Con il server ATTIVO `tmux show-environment -g <var>` esce 1 scrivendo
+    // "unknown variable" su stderr: execFileSync lo rigetta come errore, come
+    // fa per un server assente ("no server running"), ma i due esiti non sono
+    // la stessa cosa. L'assenza della variabile merita un WARN col rimedio,
+    // non l'esito «server non attivo».
+    const msg = String((err && (err.stderr || err.message)) || '');
+    if (/unknown variable/i.test(msg)) {
+      return {
+        name: 'tmux server termux-exec', ok: true, warn: true,
+        detail: 'server tmux attivo ma LD_PRELOAD non impostato (tmux: unknown variable); al primo avvio verra\' impostata, oppure: tmux set-environment -g LD_PRELOAD <libtermux-exec-ld-preload.so>',
+      };
+    }
+    // Classificazione dell'errore tmux: solo il «no server running» autentico
+    // dice che il server non c'è. Un «error connecting ... (Permission denied)»
+    // o qualunque altro fallimento lasciano la domanda aperta — il socket
+    // esiste ma questo utente non può leggerlo — e diventano «probe non
+    // verificabile» con lo stderr nel dettaglio, non un falso «server assente».
+    if (/permission denied/i.test(msg)) {
+      return {
+        name: 'tmux server termux-exec', ok: true, warn: true,
+        detail: `probe non verificabile: il socket tmux risponde "${msg}"; il server potrebbe essere attivo ma non leggibile con questo utente`,
+      };
+    }
+    if (/no server running|error connecting/i.test(msg)) {
+      return { name: 'tmux server termux-exec', ok: true, warn: true, detail: 'server tmux non attivo; probe rinviato al primo avvio' };
+    }
+    return {
+      name: 'tmux server termux-exec', ok: true, warn: true,
+      detail: `probe non verificabile: tmux ha risposto "${msg}"; stato del server non determinabile da qui`,
+    };
   }
   const match = raw.match(/^LD_PRELOAD=(.+)$/);
   const trusted = match && trustedTermuxPreload({ ...env, LD_PRELOAD: match[1] }, { platform, home: opts.home });
@@ -591,6 +645,51 @@ function checkFleetDefinitions(home, fleetDefsPath, enabled = true) {
   };
 }
 
+// Sezione «engine credentials»: per ogni engine che risolve una credenziale,
+// DA DOVE viene. Prima non esisteva alcun controllo di questo tipo: l'unico
+// blocco credenziali del doctor era quello dell'identita' (daemon/launcher), e
+// la provenienza delle chiavi degli engine non era visibile da nessuna parte —
+// una diagnosi sul campo e' arrivata a un confronto manuale di hash.
+// Non si stampa MAI un valore: solo la sorgente, il path, l'mtime e l'impronta
+// del valore troncata a 8. Un conflitto fra i file di chiavi su un engine che
+// una cella USA e' un fallimento; su un engine che nessuna cella usa e' un
+// avviso, perche' li' non c'e' ancora nulla che parta con la chiave sbagliata.
+function checkEngineCredentials(home, fleetDefsPath, enabled = true) {
+  const name = 'engine credentials';
+  if (!enabled) return { name, ok: true, warn: true, detail: 'Fleet disabilitata' };
+  const target = fleetDefsPath || path.join(home, '.nexuscrew', 'fleet.json');
+  const defs = loadDefinitions(target);
+  if (!defs) return { name, ok: true, warn: true, detail: 'fleet.json non leggibile: provenienza non verificabile' };
+  const { describeManaged, extraModelsFrom } = require('../fleet/managed.js');
+  const inUso = new Set((defs.cells || []).map((c) => c && c.engine).filter(Boolean));
+  const extraModels = extraModelsFrom(defs);
+  const righe = [];
+  const conflitti = [];
+  for (const engine of defs.engines || []) {
+    if (!engine || !engine.managed) continue;
+    const info = describeManaged(engine.managed, { home, extraModels, engineId: engine.id });
+    const envKey = info.auth;
+    if (!envKey || envKey === 'login' || envKey === 'none') continue;
+    const dove = info.credentialPath
+      ? `${info.credentialSource} (${info.credentialPath}, mtime ${new Date(info.credentialMtime).toISOString()}, sha256 ${info.credentialHash8})`
+      : info.credentialSource;
+    righe.push(`${engine.id}: ${envKey} from ${dove}`);
+    if (info.credentialConflict) conflitti.push({ engine: engine.id, inUso: inUso.has(engine.id), c: info.credentialConflict });
+  }
+  if (!righe.length) return { name, ok: true, detail: 'nessun engine con credenziale risolta' };
+  for (const { engine, c } of conflitti) {
+    const altri = c.others
+      .map((o) => `${o.path} (mtime ${new Date(o.mtime).toISOString()}, sha256 ${o.hash8})`)
+      .join(', ');
+    righe.push(`${engine}: ${c.envKey} e' definita anche in ${altri} con un valore DIVERSO (vince ${c.winner.path})`);
+  }
+  const grave = conflitti.some((k) => k.inUso);
+  const detail = righe.join(' · ');
+  if (grave) return { name, ok: false, detail };
+  if (conflitti.length) return { name, ok: true, warn: true, detail };
+  return { name, ok: true, detail };
+}
+
 // Read-only check: alternate-screen is applied per managed session, while the
 // history limit remains an operator-owned tmux setting. Do not write ~/.tmux.conf
 // or change a live server from doctor; only recommend a sufficient value.
@@ -653,6 +752,7 @@ function doctor(opts = {}) {
     checkTmuxSurvival(platform, execImpl),
     checkTokenPerms(tokenPath),
     checkFleetDefinitions(home, opts.fleetDefsPath, fleetEnabled),
+    checkEngineCredentials(home, opts.fleetDefsPath, fleetEnabled),
     checkAlternateScreenHistory(opts.alternateScreen !== undefined
       ? opts.alternateScreen : loadConfig().alternateScreen, execImpl, opts.tmuxBin),
     checkTermuxExec(opts.env, { platform, home }),
@@ -686,4 +786,5 @@ module.exports = {
   checkSshClient, checkAutossh, checkSshPermitlisten,
   checkMcpIdentity, checkIdentityAuthorityMode, checkTermuxExec,
   checkTmuxServerCwd, checkTmuxServerTermuxPreload,
+  checkEngineCredentials,
 };

package/lib/decks/routes.js

@@ -29,7 +29,17 @@ function decksRoutes({ cfg = {}, decksPath }) {
   };
   const find = (st, name) => st.decks.find((d) => d.name === name) || null;
   const checkRevision = (deck, rev) => {
-    if (deck.revision !== rev) throw httpError(409, 'deck modificato da un’altra finestra', { current: deck });
+    if (deck.revision !== rev) {
+      // Traccia il conflitto di revisione con i campi che servono a
+      // capire chi lo ha causato (nessun merge lato server in questo ciclo).
+      console.log(JSON.stringify({
+        event: 'deck-revision-conflict',
+        name: deck.name,
+        expectedRevision: rev,
+        currentRevision: deck.revision,
+      }));
+      throw httpError(409, 'deck modificato da un’altra finestra', { current: deck });
+    }
   };
 
   r.get('/', (_req, res) => {

package/lib/fleet/builtin.js

@@ -37,9 +37,11 @@ const {
 } = require('./definitions.js');
 const {
   publicCatalog, describeManaged, describeCatalogCredential, defaultShellEngine, defaultAgyEngine, defaultKimiEngine, defaultGrokEngine, defaultVlEngine,
-  CATALOG, credential: resolveProfileCredential, extraModelsFrom, knownMcpServerNames,
+  CATALOG, credential: resolveProfileCredential, extraModelsFrom, knownMcpServerNames, profileFor,
+  normalizeManagedSpec,
 } = require('./managed.js');
-const { probeModel } = require('./model-probe.js');
+const { probeModel, probeCustomEndpoint } = require('./model-probe.js');
+const { sharedProbe: defaultEndpointProbe } = require('./endpoint-probe.js');
 const { validEnvKey } = require('./env-key.js');
 const { setCredential, removeCredential } = require('./credentials.js');
 const { createLaunchBroker } = require('./launch-broker.js');
@@ -874,12 +876,57 @@ async function createBuiltinFleet(cfg = {}) {
     }
     // Se un engine sta USANDO questo modello, toglierlo lo renderebbe invalido
     // al prossimo avvio — e il messaggio arriverebbe a chi non sa cosa e'
-    // cambiato. Meglio rifiutare adesso, dicendo chi lo usa.
+    // cambiato. Meglio rifiutare adesso, dicendo chi lo usa. Un engine risolve
+    // il modello dalla dichiarazione fatta sul SUO id o sul suo profilo
+    // (declaredFor cerca in [engineId, profileId]): il ritiro di
+    // {wantedId, wantedEngine} lo rompe solo se wantedEngine e' una di quelle
+    // chiavi — un altro engine con la propria dichiarazione non c'entra.
     const usato = (defs.engines || [])
-      .filter((e) => e.managed && e.managed.model === wantedId)
+      .filter((e) => {
+        if (!e.managed || e.managed.model !== wantedId) return false;
+        if (e.id === wantedEngine) return true;
+        const profile = profileFor(e.managed.client, e.managed.provider, e.managed.credentialProfile || '');
+        return !!(profile && profile.id === wantedEngine);
+      })
       .map((e) => e.id);
-    if (usato.length) {
-      throw httpError(409, `modello in uso: ${usato.join(', ')}`);
+    // E una CELLA puo' sovrascrivere il modello del proprio engine: l'engine non
+    // lo usa, la cella si'. Guardare solo gli engine lasciava passare la
+    // rimozione e lasciava una cella che punta a un modello che non c'e' piu':
+    // il danno si manifestava al primo avvio, davanti a chi non sa cosa e'
+    // cambiato. Le chiavi sono le STESSE due della risoluzione — l'id
+    // dell'engine e quello del suo profilo — piu' l'override singolo `cell.model`,
+    // che vale per l'engine della cella.
+    // Il profilo che conta e' quello dell'engine DICHIARANTE: la seconda chiave
+    // con cui una cella riferisce un engine e' l'id del suo profilo, non quello
+    // di un altro.
+    const wantedDef = findEngine(defs, wantedEngine);
+    const wantedProfile = wantedDef && wantedDef.managed
+      ? profileFor(wantedDef.managed.client, wantedDef.managed.provider, wantedDef.managed.credentialProfile || '')
+      : null;
+    const wantedProfileId = wantedProfile && wantedProfile.id;
+    const celleUsano = (defs.cells || [])
+      .filter((c) => {
+        const perEngine = c.models || {};
+        if (perEngine[wantedEngine] === wantedId) return true;
+        if (wantedProfileId && perEngine[wantedProfileId] === wantedId) return true;
+        // `cell.model` vale per l'engine DELLA cella: e' un uso del modello
+        // chiesto solo se quella cella gira proprio sull'engine dichiarante.
+        if (c.model === wantedId) {
+          if (c.engine === wantedEngine) return true;
+          const cellEngine = findEngine(defs, c.engine);
+          const cellProfile = cellEngine && cellEngine.managed
+            ? profileFor(cellEngine.managed.client, cellEngine.managed.provider, cellEngine.managed.credentialProfile || '')
+            : null;
+          return !!(cellProfile && cellProfile.id === wantedEngine);
+        }
+        return false;
+      })
+      .map((c) => c.id);
+    if (usato.length || celleUsano.length) {
+      const parti = [];
+      if (usato.length) parti.push(`modello in uso: ${usato.join(', ')}`);
+      if (celleUsano.length) parti.push(`celle: ${celleUsano.join(', ')}`);
+      throw httpError(409, parti.join('; '));
     }
     await mutate(defs, (d) => {
       d.models = (d.models || []).filter((m) => !(m.id === wantedId && m.engine === wantedEngine));
@@ -1264,7 +1311,10 @@ async function createBuiltinFleet(cfg = {}) {
       engines: defs.engines.map((e) => {
         const out = { ...e, envKeys: Object.keys(e.env || {}).sort() };
         delete out.env;
-        if (e.managed) out.managedInfo = describeManaged(e.managed, { ...cfg, home, extraModels: extraModelsFrom(defs) });
+        if (e.managed) out.managedInfo = describeManaged(e.managed, {
+          ...cfg, home, extraModels: extraModelsFrom(defs), engineId: e.id,
+          endpointProbe: cfg.endpointProbe || defaultEndpointProbe,
+        });
         return out;
       }),
       cells: defs.cells.map((c) => {
@@ -1443,19 +1493,54 @@ async function createBuiltinFleet(cfg = {}) {
     return ['status', 'up', 'down', 'restart', 'engine', 'boot', 'define', 'edit', 'remove', 'import', 'restore', 'schema', 'definitions', 'credentials', 'model-test'];
   }
 
+  // Un engine del documento con un `baseUrl` dichiarato a mano: indirizzo e
+  // credenziale risolti per la prova, e niente altro. Il valore della chiave NON
+  // entra nel ritorno di testModel ne' in un log.
+  function customEndpointFor(engineId) {
+    const defsNow = (typeof reloadDefs === 'function' ? reloadDefs() : defs) || defs;
+    const eng = findEngine(defsNow, engineId);
+    if (!eng || !eng.managed || !eng.managed.baseUrl) return null;
+    const spec = normalizeManagedSpec(eng.managed, {
+      extraModels: extraModelsFrom(defsNow), engineId: eng.id,
+    });
+    if (!spec) return null;
+    const prof = profileFor(spec.client, spec.provider, spec.credentialProfile || '');
+    let credential = '';
+    try {
+      credential = (resolveProfileCredential(prof, {
+        client: prof.client, provider: prof.provider,
+        ...(spec.credentialProfile ? { credentialProfile: spec.credentialProfile } : {}),
+      }, cfg, home) || {}).value || '';
+    } catch (_) { credential = ''; }
+    return { endpoint: spec.baseUrl || '', credential };
+  }
+
   // «questo modello funziona con questa credenziale?», chiesto all'API invece
   // che scoperto quando la cella non parte. Vive qui e non nelle route perche'
   // la credenziale si risolve dove gia' si risolve per l'avvio: la chiave non
   // attraversa il router e non compare in nessuna risposta.
   async function testModel(engineId, model, opts = {}) {
-    const profile = CATALOG.find((p) => p.id === String(engineId || ''));
-    if (!profile) {
-      const e = new Error(`profilo sconosciuto "${engineId}"`); e.status = 404; throw e;
-    }
+    const id = String(engineId || '');
+    const profile = CATALOG.find((p) => p.id === id);
     const wanted = typeof model === 'string' ? model.trim() : '';
     if (!wanted || wanted.length > 128 || /[\x00-\x1f\x7f]/.test(wanted)) {
       const e = new Error('modello non valido'); e.status = 400; throw e;
     }
+    if (!profile) {
+      // Un engine DICHIARATO con un endpoint proprio non sta nel catalogo
+      // pubblico: rispondere 404 significava «non provabile» proprio dove la
+      // prova serve di piu' — un router interno che nessuno sorveglia. Si prova
+      // sul suo indirizzo, con le credenziali gia' risolte per quell'engine.
+      const custom = customEndpointFor(id);
+      if (!custom) {
+        const e = new Error(`profilo sconosciuto "${engineId}"`); e.status = 404; throw e;
+      }
+      const out = await probeCustomEndpoint({
+        endpoint: custom.endpoint, credential: custom.credential, model: wanted,
+        fetchImpl: opts.fetchImpl,
+      });
+      return { engine: id, model: wanted, ...out };
+    }
     const spec = {
       client: profile.client,
       provider: profile.provider,

package/lib/fleet/definitions.js

@@ -170,7 +170,7 @@ function cellIdFromTmuxSession(session) {
 //
 // Un modello dichiarato NON aggira il controllo: lo estende in modo esplicito.
 // Un id mai dichiarato resta rifiutato.
-const MAX_MODELS = 64;
+const MAX_MODELS = 128;
 const MODEL_ID_MAX = 128;
 
 function parseModel(m) {
@@ -245,7 +245,15 @@ function parseDefinitions(raw, { allowLegacyTmuxNames = true, onReject = null, o
     const models = [];
     const extraModels = new Map();
     if (d.models !== undefined) {
-      if (!Array.isArray(d.models) || d.models.length > MAX_MODELS) return null;
+      if (!Array.isArray(d.models)) return null;
+      if (d.models.length > MAX_MODELS) {
+        // Come per gli engine: il rifiuto NOMINA il limite, altrimenti chi
+        // dichiara si ritrova un 400 generico senza sapere che il cap era
+        // quello. `onIssue` porta campo/valore/regola al messaggio del comando
+        // (400 di una scrittura), `reject` alla lettura del file.
+        if (typeof onIssue === 'function') onIssue({ field: 'models', value: d.models.length, rule: `troppi modelli dichiarati, cap ${MAX_MODELS}` });
+        return reject(`fleet.json rifiutato: ${d.models.length} modelli dichiarati, cap ${MAX_MODELS}; riduci i modelli a ${MAX_MODELS} o meno`);
+      }
       const seen = new Set();
       for (const m of d.models) {
         const model = parseModel(m);
@@ -1081,7 +1089,7 @@ function atomicWrite(p, data) {
 }
 
 const CAPS = {
-  SCHEMA_VERSION, MAX_ENGINES, MAX_CELLS, MAX_ARGS, MAX_ARG_LEN,
+  SCHEMA_VERSION, MAX_ENGINES, MAX_MODELS, MAX_CELLS, MAX_ARGS, MAX_ARG_LEN,
   MAX_ENV_KEYS, MAX_ENV_KEY_LEN, MAX_ENV_VAL_LEN, MAX_LABEL_LEN,
   MAX_COMMAND_LEN, MAX_CWD_LEN, MAX_MODEL_FLAG_LEN, MAX_MODEL_VAL_LEN,
   MAX_PROMPTFLAG_LEN, MAX_PROMPT_LEN, MAX_CELL_COMMAND_LEN, MAX_TMUXSESSION_LEN,

package/lib/fleet/endpoint-probe.js

@@ -0,0 +1,146 @@
+'use strict';
+// lib/fleet/endpoint-probe.js — «l'endpoint risponde?», chiesto all'endpoint.
+//
+// Un engine managed con un `baseUrl` dichiarato a mano (un router llama.cpp, un
+// server locale, un proxy) veniva dichiarato `ready` appena il BINARIO esisteva e
+// la credenziale era a posto. Nessuno interrogava mai l'indirizzo: un router
+// spento risultava pronto, e lo si scopriva facendo partire la cella. Qui la
+// domanda si fa prima, con un GET sull'elenco dei modelli — l'unica chiamata che
+// non consuma token e non genera testo.
+//
+// TRE DISCIPLINE, che valgono quanto la sonda:
+//   1. NON BLOCCANTE OLTRE IL PROPRIO BUDGET. `refresh` e' l'unico punto che
+//      aspetta, e aspetta al massimo `timeoutMs`. Chi legge lo stato da un
+//      percorso sincrono usa `read`/`ensure`: ottiene il verdetto NOTO ADESSO e
+//      al massimo fa partire un rifornimento in sottofondo.
+//   2. UNA PROBE OGNI `ttlMs` PER ENDPOINT. `nc_status` e la UI interrogano lo
+//      stato di continuo: senza cache si tradurrebbe in una tempesta di GET
+//      verso ogni router del parco.
+//   3. GLI ENGINE DI CATALOGO NON SI SONDANO. La sonda si applica solo dove
+//      l'indirizzo e' dichiarato (provider pubblici: irraggiungibile da qui non
+//      significa rotto, e non e' compito di questo nodo misurarlo).
+
+const DEFAULT_TIMEOUT_MS = 1500;
+const DEFAULT_TTL_MS = 30000;
+
+// L'elenco modelli sta sotto `/v1/models` per le API in stile OpenAI. Un
+// `baseUrl` che dichiara gia' `/v1` non lo ripete: ripeterlo produce
+// `/v1/v1/models`, che risponde 404 e verrebbe letto come «endpoint vivo».
+function modelsProbeUrl(baseUrl) {
+  const b = String(baseUrl || '').trim().replace(/\/+$/, '');
+  if (!/^https?:\/\//i.test(b)) return null;
+  return /\/v1$/.test(b) ? `${b}/models` : `${b}/v1/models`;
+}
+
+// `host:porta` per il messaggio: e' cio' che serve a chi legge per capire QUALE
+// indirizzo non risponde, senza riversare l'URL intero nel verdetto.
+function endpointHost(baseUrl) {
+  try {
+    const u = new URL(String(baseUrl));
+    const port = u.port || (u.protocol === 'https:' ? '443' : '80');
+    return `${u.hostname}:${port}`;
+  } catch (_) { return String(baseUrl || ''); }
+}
+
+function createEndpointProbe({
+  fetchImpl = fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  ttlMs = DEFAULT_TTL_MS,
+  now = () => Date.now(),
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  log = () => {},
+} = {}) {
+  const cache = new Map();   // baseUrl -> {state, reason, at}
+  const inFlight = new Map(); // baseUrl -> Promise
+
+  // Verdetto noto ADESSO, senza toccare la rete. `null` = mai sondato.
+  function read(baseUrl) {
+    if (!modelsProbeUrl(baseUrl)) return null;
+    const hit = cache.get(baseUrl);
+    if (!hit) return null;
+    return { state: hit.state, reason: hit.reason, at: hit.at, stale: (now() - hit.at) >= ttlMs };
+  }
+
+  async function refresh(baseUrl) {
+    const url = modelsProbeUrl(baseUrl);
+    if (!url) return null;
+    if (inFlight.has(baseUrl)) return inFlight.get(baseUrl);
+    const run = (async () => {
+      const controller = new AbortController();
+      const timer = setTimer(() => controller.abort(), timeoutMs);
+      // Un timer di sonda non tiene vivo il processo.
+      if (timer && typeof timer.unref === 'function') timer.unref();
+      let verdict;
+      try {
+        const res = await fetchImpl(url, { method: 'GET', signal: controller.signal });
+        const status = res && typeof res.status === 'number' ? res.status : 0;
+        if (status >= 200 && status < 300) {
+          verdict = { state: 'ready', reason: 'ready' };
+        } else if (status === 401 || status === 403) {
+          // L'endpoint ha risposto e sta chiedendo una credenziale: e' VIVO.
+          // Se la chiave sia quella giusta lo decide il client, non questa sonda.
+          verdict = { state: 'ready', reason: 'ready' };
+        } else if (status >= 500) {
+          verdict = { state: 'unreachable', reason: `endpoint unreachable: ${endpointHost(baseUrl)} (http ${status})` };
+        } else {
+          // Qualunque altra risposta (404 compreso) e' comunque una risposta:
+          // l'indirizzo c'e' ed e' in ascolto.
+          verdict = { state: 'ready', reason: 'ready' };
+        }
+      } catch (error) {
+        const aborted = error && (error.name === 'AbortError' || error.code === 'ABORT_ERR');
+        verdict = {
+          state: 'unreachable',
+          reason: `endpoint unreachable: ${endpointHost(baseUrl)} (${aborted ? `timeout (${timeoutMs}ms)` : 'connessione rifiutata'})`,
+        };
+      } finally {
+        try { clearTimer(timer); } catch (_) {}
+      }
+      cache.set(baseUrl, { ...verdict, at: now() });
+      try { log(`sonda endpoint ${endpointHost(baseUrl)}: ${verdict.state}`); } catch (_) {}
+      return verdict;
+    })();
+    inFlight.set(baseUrl, run);
+    try { return await run; } finally { inFlight.delete(baseUrl); }
+  }
+
+  // Percorso SINCRONO: ritorna il verdetto noto (o `null`) e, se manca o e'
+  // scaduto, avvia il rifornimento senza attendere. Il primo giro dopo un
+  // avvio puo' quindi non sapere ancora; dal secondo in poi dice la verita'
+  // per tutta la durata del TTL.
+  function ensure(baseUrl) {
+    if (!modelsProbeUrl(baseUrl)) return null;
+    const hit = read(baseUrl);
+    if (!hit || hit.stale) { refresh(baseUrl).catch(() => {}); }
+    return hit ? { state: hit.state, reason: hit.reason } : null;
+  }
+
+  // Percorso ASINCRONO: attende la sonda SOLO se il verdetto e' assente o
+  // scaduto. E' quello che usa lo status, dove un'attesa breve e' ammessa e
+  // un'informazione vecchia non serve a nessuno.
+  async function status(baseUrl) {
+    const hit = read(baseUrl);
+    if (hit && !hit.stale) return { state: hit.state, reason: hit.reason };
+    return refresh(baseUrl).catch(() => null);
+  }
+
+  return {
+    read, ensure, refresh, status,
+    size: () => cache.size,
+    clear: () => cache.clear(),
+    limits: { timeoutMs, ttlMs },
+    url: modelsProbeUrl,
+    host: endpointHost,
+  };
+}
+
+// Istanza di processo: la cache deve sopravvivere alla singola chiamata, ed e'
+// esattamente cio' che evita la tempesta di probe.
+const sharedProbe = createEndpointProbe();
+
+module.exports = {
+  createEndpointProbe, sharedProbe, modelsProbeUrl, endpointHost,
+  ENDPOINT_PROBE_TIMEOUT_MS: DEFAULT_TIMEOUT_MS,
+  ENDPOINT_PROBE_TTL_MS: DEFAULT_TTL_MS,
+};