@mmmbuto/nexuscrew 0.9.52 → 0.9.54

package/lib/notify/event-feed-client.js

@@ -15,6 +15,16 @@ const BACKOFF_MIN_MS = 5000;
 const BACKOFF_MAX_MS = 60000;
 const IDLE_TIMEOUT_MS = 60000;
 const MAX_CONSECUTIVE_RESETS = 3;
+// `resync-exhausted` ferma il loop ma non deve parcheggiare la view
+// per sempre. Al tappo la view prende un cooldown a gradini — 30 s → 2 min →
+// 5 min, poi fisso — e alla scadenza paga UN tentativo di snapshot fresco.
+// Iniettabile per i test (timer veri, passi piccoli).
+const RESYNC_COOLDOWN_STEPS_MS = [30 * 1000, 2 * 60 * 1000, 5 * 60 * 1000];
+// INVARIANTE: al massimo UNO snapshot per finestra, per owner, da qualunque
+// causa di resync (409, frame malformato, oversize, seq discontinua, errore
+// di trasporto). È la garanzia strutturale: le vie singole possono cambiare,
+// il tetto delle richieste no. Di default 30 s, iniettabile per i test.
+const MIN_SNAPSHOT_INTERVAL_MS = 30 * 1000;
 
 // Ingress budgets: 120 frames/min and 1 MiB/min per owner, plus a separate
 // federated global window of 480 frames/min and 4 MiB/min. The counters are
@@ -36,11 +46,39 @@ const SNAPSHOT_MAX_CELLS = 1000;
 const SNAPSHOT_ELEMENT_MAX_BYTES = 16 * 1024;
 const SNAPSHOT_ID_MAX_CHARS = 64;
 
+// Lo snapshot è JSON DICHIARATO: se la risposta dichiara un media type, questo
+// dev'essere application/json (i parametri come charset sono ammessi). Un
+// corpo che parsisce ma viaggia come text/plain non è la superficie dello
+// snapshot — quale che sia il suo contenuto, non decide niente. La
+// dichiarazione ASSENTE (proxy che spoglia gli header, trasporti degradati
+// verso la view) resta tollerata: la regola colpisce chi dichiara un tipo
+// sbagliato, non chi non dichiara.
+function isJsonContentType(value) {
+  if (typeof value !== 'string') return false;
+  return value.split(';')[0].trim().toLowerCase() === 'application/json';
+}
+
+// Lettura difensiva dell'header: risposte senza headers (stub, trasporti
+// degradati) valgono come dichiarazione ASSENTE, che il validatore tollera.
+function contentTypeOf(r) {
+  try {
+    return r && r.headers && typeof r.headers.get === 'function' ? r.headers.get('content-type') : null;
+  } catch (_) {
+    return null;
+  }
+}
+
 function createEventFeedClient(opts = {}) {
   // deps: { nodesPath, token(), eventsHub, now, fetchImpl, log }
   const fetchImpl = opts.fetchImpl || fetch;
   const now = opts.now || Date.now;
   const log = typeof opts.log === 'function' ? opts.log : () => {};
+  const cooldownSteps = Array.isArray(opts.resyncCooldownStepsMs) && opts.resyncCooldownStepsMs.length > 0
+    ? opts.resyncCooldownStepsMs
+    : RESYNC_COOLDOWN_STEPS_MS;
+  const minSnapshotIntervalMs = typeof opts.minSnapshotIntervalMs === 'number' && opts.minSnapshotIntervalMs >= 0
+    ? opts.minSnapshotIntervalMs
+    : MIN_SNAPSHOT_INTERVAL_MS;
   // ownerId -> view state {cursor, generation, asks, notifications, fleetState,
   //   stale, lastError}; generation guards against obsolete fetches.
   const views = new Map();
@@ -62,14 +100,60 @@ function createEventFeedClient(opts = {}) {
     return views.get(ownerId);
   }
 
+  // Asks this node knows are CLOSED on the owner. The owner's snapshot can still
+  // carry one for a moment (its closing frame and our re-snapshot race), and the
+  // UI would re-import it — the card that comes back after the X.
+  // The tombstone carries a TTL and the view epoch it was made in: an id reused
+  // after an owner reset must NOT stay suppressed forever.
+  const ASK_TOMBSTONE_TTL_MS = 10 * 60 * 1000;
+  const askTombstones = new Map(); // `${ownerId}|${askId}` -> {at, epoch}
+
+  function askTombstoneKey(ownerId, askId) { return `${ownerId}|${askId}`; }
+
+  function noteAskClosed(ownerId, askId, epoch) {
+    if (!ownerId || !askId) return;
+    askTombstones.set(askTombstoneKey(ownerId, askId), { at: now(), epoch });
+  }
+
+  function askIsClosed(ownerId, askId, epoch) {
+    const key = askTombstoneKey(ownerId, askId);
+    const hit = askTombstones.get(key);
+    if (!hit) return false;
+    if (now() - hit.at > ASK_TOMBSTONE_TTL_MS) { askTombstones.delete(key); return false; }
+    if (typeof hit.epoch === 'number' && typeof epoch === 'number' && hit.epoch !== epoch) return false;
+    return true;
+  }
+
+  function dropAskFromView(ownerId, askId) {
+    const view = viewFor(ownerId);
+    view.asks = view.asks.filter((a) => (a.ownerAskId || a.id) !== askId);
+    return view;
+  }
+
   // One resync round that ended WITHOUT a usable frame counts as a reset: a
   // peer that keeps asking to resync (409 reset-required / cursor-future, or a
   // frame from an unknown epoch) would otherwise be re-snapshotted forever.
   // Past the cap the view goes to the error state and the poll gate stops it;
   // a single healthy frame clears the streak.
+  // Arma (o riarma) il cooldown della view al gradino successivo della
+  // scala. Vale sia per l'esaurimento del tappo (noteReset) sia per un
+  // tentativo di recupero fallito (poll): in entrambi i casi la view torna a
+  // chiedere SOLO alla scadenza, un tentativo per scadenza.
+  function armResyncCooldown(view, why) {
+    view.resyncExhaustions = (view.resyncExhaustions || 0) + 1;
+    const step = cooldownSteps[Math.min(view.resyncExhaustions - 1, cooldownSteps.length - 1)];
+    view.resyncBlockedUntil = now() + step;
+    log(`event-feed-client: ${String(view.ownerId || '').slice(0, 8)}… ${why}: cooldown ${Math.round(step / 1000)} s (exhaustions ${view.resyncExhaustions})`);
+  }
+
   function noteReset(view) {
     view.consecutiveResets = (view.consecutiveResets || 0) + 1;
     if (view.consecutiveResets >= MAX_CONSECUTIVE_RESETS) {
+      // Il tappo ferma il loop, ma la view non resta parcheggiata: il
+      // cooldown cresce a ogni riesaurimento SENZA un frame sano in mezzo (una
+      // connessione che funziona riporta la scala al primo gradino, vedi
+      // streamOnce) e alla scadenza paga uno snapshot fresco (vedi poll).
+      armResyncCooldown(view, 'resync exhausted');
       view.stale = true;
       view.lastError = 'resync-exhausted';
     }
@@ -99,12 +183,24 @@ function createEventFeedClient(opts = {}) {
     const view = viewFor(ownerId);
     if (gen !== generation) return false;
     view.cursor = snap.cursor || null;
-    view.asks = Array.isArray(snap.asks) ? snap.asks.map((a) => ({ ...a, ownerId })) : [];
+    // A snapshot taken before the owner processed a dismiss still carries the
+    // ask: the tombstone is what keeps it from coming back.
+    view.asks = Array.isArray(snap.asks)
+      ? snap.asks
+        .filter((a) => a && !askIsClosed(ownerId, a.ownerAskId || a.id, snap.viewEpoch))
+        .map((a) => ({ ...a, ownerId }))
+      : [];
     view.notifications = Array.isArray(snap.notifications) ? snap.notifications.map((e) => ({ ...e, ownerId })) : [];
     view.fleetState = snap.fleetState || null;
     view.askReplyAccess = snap.askReplyAccess === true;
     view.viewEpoch = snap.viewEpoch;
     view.stale = false;
+    // Lo snapshot fresco è la guarigione visibile: stale torna falso e
+    // l'ultimo errore cessa di essere mostrato. Lo streak NON si tocca qui:
+    // il conto dei reset misura i round SENZA frame sano, e ogni round di
+    // ricognizione inizia con uno snapshot — azzerarlo qui annullerebbe il
+    // tappo anti-reset. Lo sblocco dello streak sta alla scadenza del cooldown.
+    view.lastError = null;
     view.generation = gen;
     return true;
   }
@@ -133,6 +229,10 @@ function createEventFeedClient(opts = {}) {
       opts.eventsHub.broadcast({ type: 'ask', ownerId: envelope.ownerId, eventId: envelope.eventId,
         ask: { id: f.askId, question: f.question, options: f.options, session: f.session, ownerId: envelope.ownerId } });
     } else if (f.type === 'ask-closed') {
+      // The owner says the ask is closed: the VIEW drops it too, not only the
+      // UI, or the next state read hands the card back.
+      const closedView = dropAskFromView(envelope.ownerId, f.askId);
+      if (f.outcome === 'dismissed') noteAskClosed(envelope.ownerId, f.askId, closedView.viewEpoch);
       opts.eventsHub.broadcast({ type: f.outcome === 'dismissed' ? 'ask-dismissed' : 'ask-answered',
         id: f.askId, ownerId: envelope.ownerId, eventId: envelope.eventId });
     } else if (f.type === 'file-notice') {
@@ -241,7 +341,7 @@ function createEventFeedClient(opts = {}) {
           const dataLine = block.split('\n').find((l) => l.startsWith('data: '));
           if (!dataLine) continue;
           // Frame cap BEFORE JSON.parse.
-          if (dataLine.length > 16 * 1024) { log('event-feed-client: oversized frame, resync'); view.cursor = null; return; }
+          if (dataLine.length > 16 * 1024) { log('event-feed-client: oversized frame, resync'); view.cursor = null; noteReset(view); return; }
           // Ingress budget, counted per FRAME on the wire BEFORE it is parsed or
           // applied: over the cap this peer is disconnected by name and blocked
           // for the rest of its window, while the other owners keep streaming.
@@ -260,7 +360,7 @@ function createEventFeedClient(opts = {}) {
             return;
           }
           let envelope;
-          try { envelope = JSON.parse(dataLine.slice(6)); } catch (_) { view.cursor = null; return; }
+          try { envelope = JSON.parse(dataLine.slice(6)); } catch (_) { view.cursor = null; noteReset(view); return; }
           // Owner mismatch on a frame: disconnect, never apply.
           if (envelope.ownerId !== ownerId) { log('event-feed-client: owner mismatch, disconnect'); return; }
           // Sequence continuity within the same epoch; anything else resyncs.
@@ -271,9 +371,10 @@ function createEventFeedClient(opts = {}) {
             noteReset(view);
             return;
           }
-          if (view.lastSeq !== undefined && Number(sStr) !== view.lastSeq + 1) { view.cursor = null; return; }
+          if (view.lastSeq !== undefined && Number(sStr) !== view.lastSeq + 1) { view.cursor = null; noteReset(view); return; }
           view.lastSeq = Number(sStr);
           view.consecutiveResets = 0; // a usable frame: the streak is over
+          view.resyncExhaustions = 0; // and a working stream: the cooldown ladder back to the first step
           view.cursor = `${epochStr}:${sStr}`;
           reemit(envelope);
         }
@@ -308,56 +409,174 @@ function createEventFeedClient(opts = {}) {
     return true;
   }
 
-  async function snapshotOnce(peer, ownerId, store) {
-    const view = viewFor(ownerId);
-    const gen = generation;
-    const r = await fetchImpl(routeUrl(peer, '/event-feed/snapshot'), {
-      headers: identityHeaders(peer, store),
-    });
-    if (!r.ok) { view.stale = true; throw new Error(`snapshot HTTP ${r.status}`); }
-    // Size cap BEFORE JSON.parse: a body over the server budget is refused on
-    // sight, never parsed.
-    const text = await r.text();
-    if (Buffer.byteLength(text, 'utf8') > 3 * 1024 * 1024) {
-      view.stale = true; view.lastError = 'snapshot-oversize';
-      return false;
-    }
-    const snap = JSON.parse(text);
-    // Owner mismatch on the snapshot: disconnect, never apply.
-    if (snap.ownerId !== ownerId) {
-      view.stale = true; view.lastError = 'owner-mismatch';
-      return false;
-    }
-    // Per-element sanity over EVERY list, not just the notify history: bounded
-    // id, bounded element, and the count caps. A snapshot that breaks any of
-    // them is refused whole — never applied in part.
+  // Il VALIDATORE unico dello snapshot: entrambe le vie (sottoscritta e non
+  // sottoscritta) passano da qui. Niente logica duplicata: una regola nuova
+  // vale per tutte le porte. Il pre-check della dimensione prima del parse
+  // resta nei chiamanti come scorciatoia (non si paga il parse di un corpo
+  // rifiutato): la regola vive qui.
+  //
+  // Due PROFILI dello stesso contratto, non due validatori:
+  //   - 'decision' è ciò che rende l'elenco asks AUTOREVOLE per la chiusura
+  //     degli alias importati (ownerId atteso, resyncRequired ben formato e
+  //     non dichiarante, content-type dichiarato corretto, asks elenco di
+  //     oggetti con id stringa 1..64, cap di pagina e per-elemento, cap del
+  //     corpo). È il profilo della PORTA: la decisione di chiusura legge SOLO
+  //     questi campi, e un campo che la decisione non legge non può tener
+  //     aperta una card che l'owner ha chiuso (la vista che non si può
+  //     applicare per colpa di cursor o notifications è un problema della
+  //     vista, non una prova che l'ask sia ancora viva).
+  //   - 'view' (default) aggiunge lo SCHEMA COMPLETO dei campi che la vista
+  //     applica (cursor, viewEpoch, askReplyAccess, notifications, fleetState,
+  //     i campi interni di ogni ask): qui un tipo sbagliato in QUALUNQUE
+  //     punto non è mai 'ok' (reason 'snapshot-schema:<campo>') — lo snapshot
+  //     non si applica, niente applicazione parziale.
+  // Produttore di riferimento: lib/notify/event-feed-routes.js buildSnapshot
+  // (emette sempre i campi della view e marca resyncRequired a ogni cap).
+  function validateSnapshot(ownerId, snap, bytes, contentType, profile = 'view') {
+    if (!snap || typeof snap !== 'object') return { ok: false, reason: 'shape' };
+    if (bytes > 3 * 1024 * 1024) return { ok: false, reason: 'snapshot-oversize' };
+    // ownerId: stringa E uguale all'atteso — un valore di altro tipo non può
+    // coincidere con l'id atteso, quindi owner-mismatch copre anche la forma.
+    if (snap.ownerId !== ownerId) return { ok: false, reason: 'owner-mismatch' };
+    // Uno snapshot incompleto è un floor, non un tutto: mai autorevole.
+    if (snap.resyncRequired === true) return { ok: false, reason: 'snapshot-resync-required' };
+    // Il trasporto dichiara il tipo: dichiarato ma non application/json non è
+    // la superficie dello snapshot. L'ASSENZA di dichiarazione è tollerata.
+    if (contentType != null && !isJsonContentType(contentType)) return { ok: false, reason: 'snapshot-content-type' };
+    const schema = (field) => ({ ok: false, reason: `snapshot-schema:${field}` });
+    // resyncRequired, quando c'è, è un booleano del produttore: 1, "true" o
+    // un oggetto sono un'altra versione del contratto, non un caso limite.
+    if (snap.resyncRequired !== undefined && typeof snap.resyncRequired !== 'boolean') return schema('resyncRequired');
+    // asks È l'elenco che decide la chiusura degli alias: OBBLIGATORIO, array.
+    // Senza questa richiesta uno snapshot senza asks passava come 'ok' e la
+    // riconciliazione chiudeva alias ancora aperti su un elenco che non c'era.
+    if (!Array.isArray(snap.asks)) return schema('asks');
     const boundedId = (id) => typeof id === 'string' && id.length > 0 && id.length <= SNAPSHOT_ID_MAX_CHARS;
     const boundedElement = (e) => !!e && typeof e === 'object'
       && Buffer.byteLength(JSON.stringify(e), 'utf8') <= SNAPSHOT_ELEMENT_MAX_BYTES;
-    if (Array.isArray(snap.asks)
-      && (snap.asks.length > SNAPSHOT_MAX_ASKS
-        || !snap.asks.every((a) => boundedElement(a) && boundedId(a && a.id)))) {
-      view.stale = true; view.lastError = 'snapshot-element-oversize';
-      return false;
+    // Cap di pagina e per-elemento: identità e misura. Id non stringa o vuoto,
+    // elemento non oggetto o fuori budget → 'snapshot-element-oversize'
+    // (mapping storico invariato, il cap resta un cap). Il cap di pagina vale
+    // a quota PIENA (>= SNAPSHOT_MAX_ASKS): il produttore marca resyncRequired
+    // proprio a quella quota, quindi un elenco al cap SENZA marcatore non è
+    // una forma dell'owner e non prova l'assenza di nessuna domanda.
+    if (snap.asks.length >= SNAPSHOT_MAX_ASKS
+      || !snap.asks.every((a) => boundedElement(a) && boundedId(a && a.id))) {
+      return { ok: false, reason: 'snapshot-element-oversize' };
+    }
+    if (profile !== 'view') return { ok: true };
+    // — da qui in poi solo lo schema della VISTA —
+    // Flag e scalari col tipo esatto con cui la vista li applica (il
+    // produttore li emette sempre: un tipo diverso è un'altra versione, non
+    // un caso limite da tollerare). Assenti restano ammessi dove applySnapshot
+    // ha un default; sbagliati mai.
+    if (snap.cursor !== undefined && snap.cursor !== null && typeof snap.cursor !== 'string') return schema('cursor');
+    if (snap.viewEpoch !== undefined && snap.viewEpoch !== null && typeof snap.viewEpoch !== 'number') return schema('viewEpoch');
+    if (snap.askReplyAccess !== undefined && typeof snap.askReplyAccess !== 'boolean') return schema('askReplyAccess');
+    if (snap.notifications !== undefined && snap.notifications !== null
+      && !Array.isArray(snap.notifications)) return schema('notifications');
+    if (snap.fleetState !== undefined && snap.fleetState !== null
+      && (typeof snap.fleetState !== 'object' || Array.isArray(snap.fleetState))) return schema('fleetState');
+    if (snap.fleetState && typeof snap.fleetState === 'object') {
+      if (snap.fleetState.available !== undefined && typeof snap.fleetState.available !== 'boolean') return schema('fleetState');
+      if (snap.fleetState.cells !== undefined && !Array.isArray(snap.fleetState.cells)) return schema('fleetState');
     }
     if (Array.isArray(snap.notifications)
       && (snap.notifications.length > SNAPSHOT_MAX_NOTIFY
         || !snap.notifications.every((e) => boundedElement(e) && boundedId(e && e.eventId)))) {
-      view.stale = true; view.lastError = 'snapshot-element-oversize';
-      return false;
+      return { ok: false, reason: 'snapshot-element-oversize' };
     }
     if (snap.fleetState && typeof snap.fleetState === 'object') {
       const cells = Array.isArray(snap.fleetState.cells) ? snap.fleetState.cells : [];
       if (cells.length > SNAPSHOT_MAX_CELLS || !boundedElement(snap.fleetState)
         || !cells.every((c) => boundedElement(c) && boundedId(c && c.cell))) {
-        view.stale = true; view.lastError = 'snapshot-element-oversize';
-        return false;
+        return { ok: false, reason: 'snapshot-element-oversize' };
+      }
+    }
+    // Ogni ask: i campi che la card e la risposta usano davvero, col tipo del
+    // produttore. Assente è ammesso dove il produttore omette (options, ts);
+    // sbagliato mai — un numero al posto dell'id owner non deve diventare una
+    // chiave di risposta.
+    const askFieldsOk = (a) => (a.ownerAskId === undefined || (typeof a.ownerAskId === 'string' && a.ownerAskId.length > 0))
+      && (a.question === undefined || typeof a.question === 'string')
+      && (a.options === undefined || Array.isArray(a.options))
+      && (a.session === undefined || typeof a.session === 'string')
+      && (a.ts === undefined || typeof a.ts === 'number');
+    if (!snap.asks.every(askFieldsOk)) return schema('asks');
+    return { ok: true };
+  }
+
+  // Uno snapshot per finestra, per owner, da qualunque chiamante (poll della
+  // view o porta). ESITO strutturato: { state: 'applied' | 'failed' |
+  // 'skipped', asks?, appliedToView? }.
+  //   - profilo 'view' (default, il poll): lo schema completo decide; solo un
+  //     snapshot pienamente valido entra nella view ('applied' qui significa
+  //     applicato davvero);
+  //   - profilo 'decision' (la porta): decide il contratto della CHIUSURA. Se
+  //     lo snapshot è autorevole per la decisione ma NON applicabile alla
+  //     vista (cursor malformato, notifications di tipo sbagliato, …) la
+  //     vista resta ferma e STALE con la sua causa — ma l'elenco asks torna
+  //     comunque alla porta, che è autorizzata a decidere: un campo che la
+  //     chiusura non legge non può tenere aperta una card chiusa dall'owner.
+  async function snapshotOnce(peer, ownerId, store, { profile = 'view' } = {}) {
+    const view = viewFor(ownerId);
+    // INVARIANTE (punto d'ingresso, per owner): al massimo uno snapshot per
+    // finestra, da qualunque causa di resync. Se la finestra non è trascorsa
+    // non parte nessuna richiesta e NON si tocca nulla: né la scala, né il
+    // cooldown di recupero — il campo della finestra è separato
+    // (nextSnapshotAllowedAt) proprio perché i due meccanismi non si
+    // mangino a vicenda. Lo stato resta stale e la visura in state() mostra
+    // quando il prossimo tentativo è lecito.
+    const since = view.lastSnapshotAt === undefined
+      ? Number.POSITIVE_INFINITY
+      : now() - view.lastSnapshotAt;
+    if (since < minSnapshotIntervalMs) {
+      view.stale = true;
+      view.nextSnapshotAllowedAt = view.lastSnapshotAt + minSnapshotIntervalMs;
+      return { state: 'skipped' };
+    }
+    view.lastSnapshotAt = now();
+    view.nextSnapshotAllowedAt = null;
+    const gen = generation;
+    const r = await fetchImpl(routeUrl(peer, '/event-feed/snapshot'), {
+      headers: identityHeaders(peer, store),
+    });
+    if (!r.ok) { view.stale = true; throw new Error(`snapshot HTTP ${r.status}`); }
+    // Size cap BEFORE JSON.parse: a body over the server budget is refused on
+    // sight, never parsed. La regola vive nel validatore unico; qui è la
+    // scorciatoia che evita di pagare il parse di un corpo già rifiutato.
+    const text = await r.text();
+    const bytes = Buffer.byteLength(text, 'utf8');
+    if (bytes > 3 * 1024 * 1024) {
+      view.stale = true; view.lastError = 'snapshot-oversize';
+      return { state: 'failed' };
+    }
+    const snap = JSON.parse(text);
+    // Il contratto della decisione decide l'ESITO dello snapshot; lo schema
+    // della vista decide l'APPLICAZIONE. Due giudizi, una sola funzione di
+    // regole.
+    const decision = profile === 'view'
+      ? null
+      : validateSnapshot(ownerId, snap, bytes, contentTypeOf(r), 'decision');
+    const forView = validateSnapshot(ownerId, snap, bytes, contentTypeOf(r), 'view');
+    if (profile !== 'view' && !decision.ok) {
+      // La causa resta in lastError: è ciò che l'operatore (e il cooldown
+      // riarmato) mostrano finché l'owner non torna sanitario.
+      view.stale = true; view.lastError = decision.reason;
+      return { state: 'failed' };
+    }
+    if (!forView.ok) {
+      if (profile !== 'view') {
+        // Autorevole per la chiusura, non applicabile alla vista: la vista
+        // resta com'è (stale, con la causa sua), la decisione va avanti.
+        view.stale = true; view.lastError = forView.reason;
+        return { state: 'applied', asks: snap.asks, appliedToView: false };
       }
+      view.stale = true; view.lastError = forView.reason;
+      return { state: 'failed' };
     }
-    // A snapshot over the server budget is a floor, not a whole: resync.
-    if (snap.resyncRequired) { view.stale = true; return false; }
     applySnapshot(ownerId, snap, gen);
-    return true;
+    return { state: 'applied', asks: snap.asks, appliedToView: true };
   }
 
   // One reconciliation round across every enabled peer. Never throws.
@@ -370,18 +589,68 @@ function createEventFeedClient(opts = {}) {
     await Promise.all(peers.map(async (peer) => {
       const ownerId = peer.nodeId;
       if (running.has(ownerId)) return; // one loop per pair
+      // Il guard vale per TUTTO il round, non solo per lo stream: due poll
+      // sovrapposti (tick + backoff, o macchina carica) facevano due snapshot
+      // nella stessa finestra e il secondo, senza il flag di recupero,
+      // saltava il riarma del cooldown. streamOnce
+      // sovrascrive lo slot col vero handle di abort.
+      const slot = { abort: () => {} };
+      running.set(ownerId, slot);
       const view = viewFor(ownerId);
       try {
-        if (view.unsupported || (view.consecutiveResets || 0) >= MAX_CONSECUTIVE_RESETS
-          || (view.ingressBlockedUntil || 0) > Date.now()) return;
-        if (!view.capabilityChecked) {
-          const ok = await checkCapability(peer, ownerId);
-          if (!ok) return;
+        // L'invariante PRIMA del consumo del cooldown: se la finestra non è
+        // trascorsa il tick non fa nulla — non consuma la scadenza del
+        // cooldown di recupero (il tentativo vero avverrà a finestra passata,
+        // col suo flag di recupero intatto) e non tocca il conto dei reset.
+        if (!view.cursor && view.lastSnapshotAt !== undefined
+          && now() - view.lastSnapshotAt < minSnapshotIntervalMs) {
+          view.stale = true;
+          return;
         }
-        if (!view.cursor) {
-          const ok = await snapshotOnce(peer, ownerId, store);
-          if (!ok) return;
+        // Il cooldown scaduto paga UN tentativo e azzera lo streak: se il
+        // tentativo fallisce, una nuova sequenza di reset deve poter
+        // ri-esaurire e ri-armare il cooldown al gradino successivo. Finché il
+        // cooldown è in piedi nessuna richiesta parte (il tappo resta in piedi).
+        let recovery = false;
+        if (view.resyncBlockedUntil) {
+          if (now() < view.resyncBlockedUntil) return;
+          view.resyncBlockedUntil = null;
+          view.consecutiveResets = 0;
+          recovery = true;
+          log(`event-feed-client: ${ownerId.slice(0, 8)}… resync cooldown expired: one fresh snapshot attempt`);
         }
+        if (view.unsupported || (view.ingressBlockedUntil || 0) > Date.now()) return;
+        // La fase di ACQUISIZIONE del tentativo (capability + snapshot) ha UN
+        // SOLO punto di uscita per gli esiti non riusciti: throw, timeout,
+        // abort e 'failed' convergono tutti lì — non un ramo per tipo di
+        // errore, così il prossimo modo di fallire non sfugge. Un fallimento
+        // in questa fase con il cooldown scaduto RIARMA il gradino successivo
+        // (un tentativo per scadenza, la causa resta in lastError); l'errore
+        // lanciato si risolleva per il catch esterno (stale, lastError,
+        // backoff). Lo stream resta fuori dalla fase: un suo errore dopo uno
+        // snapshot riuscito è regime di trasporto (backoff), non di resync.
+        // 'skipped' non è un fallimento: l'invariante della finestra ha solo
+        // posticipato la richiesta, la scala non si tocca.
+        let attemptError = null;
+        let snapState = null; // null = tentativo non fatto (cursor già valido)
+        try {
+          if (!view.capabilityChecked) {
+            const capOk = await checkCapability(peer, ownerId);
+            if (!capOk) return; // senza la capability il gate blocca: nessun tentativo fatto
+          }
+          if (!view.cursor) {
+            snapState = await snapshotOnce(peer, ownerId, store); // profilo view
+          }
+        } catch (e) {
+          attemptError = e;
+        }
+        if (attemptError || (snapState && snapState.state === 'failed')) {
+          if (recovery) armResyncCooldown(view, attemptError ? 'recovery attempt failed' : 'recovery snapshot failed');
+        }
+        if (attemptError) throw attemptError;
+        // Un tentativo fallito o posticipato ferma il round; NESSUN tentativo
+        // (cursor già valido) va dritto allo stream.
+        if (snapState && snapState.state !== 'applied') return;
         await streamOnce(peer, ownerId, store);
       } catch (e) {
         view.stale = true;
@@ -393,6 +662,10 @@ function createEventFeedClient(opts = {}) {
         const delay = backoffMs(peer);
         log(`event-feed-client: ${ownerId.slice(0, 8)}… retry in ${delay} ms (${view.lastError})`);
         setTimeout(() => { void poll(); }, delay);
+      } finally {
+        // Libera lo slot solo se è ancora il NOSTRO: se il round è arrivato a
+        // streamOnce, quello ha già messo (e alla fine tolto) il suo slot vero.
+        if (running.get(ownerId) === slot) running.delete(ownerId);
       }
     }));
   }
@@ -421,6 +694,12 @@ function createEventFeedClient(opts = {}) {
     return {
       views: [...views.entries()].map(([ownerId, v]) => ({
         ownerId, cursor: v.cursor, viewEpoch: v.viewEpoch, stale: v.stale,
+        // Diagnostica (doctor / feed-state): dove la view è e quanto le
+        // manca — il cooldown residuo si legge con un confronto col clock.
+        resyncBlockedUntil: v.resyncBlockedUntil || null,
+        resyncExhaustions: v.resyncExhaustions || 0,
+        // L'attesa dell'invariante finestra, separata dal cooldown.
+        nextSnapshotAllowedAt: v.lastSnapshotAt === undefined ? null : v.lastSnapshotAt + minSnapshotIntervalMs,
         // Both sides of the merge matter to the UI: the answer/dismiss gate
         // (askReplyAccess) and the ingress/error state of the view.
         askReplyAccess: v.askReplyAccess === true,
@@ -432,7 +711,100 @@ function createEventFeedClient(opts = {}) {
     };
   }
 
-  return { start, stop, poll, state, reemit, viewFor };
+  // A dismiss this node has CONFIRMED with the owner (the relay returned 2xx, or
+  // the owner said so in a frame): only then does the view forget the ask, and
+  // only then is it tombstoned. An uncertain or failed dismiss hides nothing.
+  function dismissConfirmed(ownerId, askId) {
+    const view = dropAskFromView(ownerId, askId);
+    noteAskClosed(ownerId, askId, view.viewEpoch);
+    return true;
+  }
+
+  // Esito TIPIZZATO: {status:'ok', asks} | {status:'skipped'|'pending'|'error',
+  // reason, retryAt}. SOLO 'ok' è autorevole (snapshot fresco, col contratto
+  // della decisione soddisfatto, acquisito in questa chiamata): uno skip, un
+  // pending, una finestra chiusa, un errore o un timeout non decidono MAI la
+  // chiusura di un alias.
+  const doorWindowAt = new Map(); // ownerId -> ultimo tentativo (owner non sottoscritti)
+  const doorInFlight = new Set(); // ownerId -> tentativo in volo (owner sottoscritti)
+  const DOOR_TIMEOUT_MS = 3000;
+  function doorTimeoutPromise() {
+    return new Promise((resolve) => {
+      const t = setTimeout(() => resolve(null), DOOR_TIMEOUT_MS);
+      if (typeof t.unref === 'function') t.unref();
+    });
+  }
+  async function ownerSnapshotAsks(ownerId) {
+    const store = opts.loadStore();
+    if (!store) return { status: 'error', reason: 'no-store' };
+    const id = String(ownerId);
+    const peer = (store.nodes || []).find((n) => n && n.nodeId === id && n.token && n.localPort);
+    if (!peer) return { status: 'error', reason: 'peer-unknown' };
+    if (peer.eventsReceive === true) {
+      if (doorInFlight.has(id)) {
+        const view = views.get(id);
+        const retryAt = (view && typeof view.lastSnapshotAt === 'number' ? view.lastSnapshotAt : now()) + minSnapshotIntervalMs;
+        return { status: 'pending', reason: 'attempt-in-flight', retryAt };
+      }
+      doorInFlight.add(id);
+      let state = null;
+      try {
+        // Profilo DECISION: la porta decide la chiusura degli alias, legge
+        // l'elenco che la decisione usa — e solo quello. La vista, nello
+        // stesso snapshotOnce, applica il suo schema completo o resta ferma.
+        state = await Promise.race([snapshotOnce(peer, id, store, { profile: 'decision' }), doorTimeoutPromise()]);
+      } catch (_) {
+        return { status: 'error', reason: 'transport' };
+      } finally {
+        doorInFlight.delete(id);
+      }
+      const view = views.get(id);
+      const retryAt = (view && typeof view.lastSnapshotAt === 'number' ? view.lastSnapshotAt : now()) + minSnapshotIntervalMs;
+      if (state === null) return { status: 'pending', reason: 'door-timeout', retryAt };
+      if (state.state === 'skipped') return { status: 'skipped', reason: 'window', retryAt };
+      if (state.state === 'applied') {
+        // L'elenco autorevole è quello dello snapshot: anche quando la vista
+        // non ha potuto applicarlo (appliedToView false) la decisione ha il
+        // suo contratto soddisfatto.
+        return Array.isArray(state.asks)
+          ? { status: 'ok', asks: state.asks }
+          : { status: 'error', reason: 'applied-without-view' };
+      }
+      return { status: 'error', reason: 'snapshot-failed' };
+    }
+    const last = doorWindowAt.get(id);
+    if (last !== undefined && now() - last < minSnapshotIntervalMs) {
+      return { status: 'skipped', reason: 'window', retryAt: last + minSnapshotIntervalMs };
+    }
+    doorWindowAt.set(id, now());
+    // UN AbortController per fetch E corpo: un owner che manda gli header e
+    // non chiude il corpo non può appendere chi ha chiesto lo snapshot.
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), DOOR_TIMEOUT_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+    try {
+      const r = await fetchImpl(routeUrl(peer, '/event-feed/snapshot'), {
+        headers: identityHeaders(peer, store), signal: ctrl.signal,
+      });
+      if (!r.ok) return { status: 'error', reason: `http-${r.status}` };
+      const text = await r.text();
+      const bytes = Buffer.byteLength(text, 'utf8');
+      let snap;
+      try { snap = JSON.parse(text); } catch (_) { return { status: 'error', reason: 'shape' }; }
+      // STESSO validatore della via sottoscritta, allo STESSO profilo
+      // decisionale: ownerId atteso, content-type, resyncRequired e i cap
+      // dell'elenco decidono qui esattamente come decidono là.
+      const verdict = validateSnapshot(id, snap, bytes, contentTypeOf(r), 'decision');
+      if (!verdict.ok) return { status: 'error', reason: verdict.reason };
+      return { status: 'ok', asks: snap.asks };
+    } catch (_) {
+      return { status: 'error', reason: 'transport' };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return { start, stop, poll, state, reemit, viewFor, dismissConfirmed, ownerSnapshotAsks };
 }
 
 module.exports = { createEventFeedClient };