@mmmbuto/nexuscrew 0.9.28 → 0.9.30

package/lib/notify/event-feed.js

@@ -0,0 +1,328 @@
+'use strict';
+// lib/notify/event-feed.js — owner-side event feed: a per-peer ring with the
+// scope applied BEFORE insertion, a per-peer view epoch + sequence, an atomic
+// replay-to-live barrier, backpressure via write(false), heartbeats, bounded
+// live queues and bounded counters.
+//
+// Design points that are security decisions, not preferences:
+//   - The ring holds ONLY what the peer may see. Filtering happens before
+//     insertion, never at read time: a later grant change invalidates the
+//     whole view (epoch bump + ring wipe), it does not "re-filter" history.
+//   - The cursor is per peer view: `viewEpoch:seq`. The epoch changes on owner
+//     restart and on every grant/scope change, so an old cursor can never be
+//     mistaken for a live one, and the sequence never leaks a global event
+//     count (hidden cells stay uncountable).
+//   - write(false) stops the socket until drain: production to THAT stream
+//     pauses, the ring keeps recording, the peer's other paths are untouched.
+//   - Budgets are first-threshold: whichever of events/bytes/time trips first
+//     prunes the ring, so no single dimension can grow unbounded.
+
+const HEARTBEAT_MS = 20000;
+const FRAME_MAX_BYTES = 16 * 1024; // cap BEFORE any JSON.parse downstream
+const RING_MAX_EVENTS = 512;
+const RING_MAX_BYTES = 1024 * 1024;
+const RING_MAX_MS = 15 * 60 * 1000;
+const LIVE_QUEUE_MAX_FRAMES = 128;
+const LIVE_QUEUE_MAX_BYTES = 256 * 1024;
+const MAX_ENABLED_PEERS = 8;
+const OPENS_PER_MIN = 6;
+
+function defaultNow() { return Date.now(); }
+
+function createEventFeed(opts = {}) {
+  const now = opts.now || defaultNow;
+  const heartbeatMs = opts.heartbeatMs || HEARTBEAT_MS;
+  const frameMaxBytes = opts.frameMaxBytes || FRAME_MAX_BYTES;
+  const maxPeers = opts.maxPeers || MAX_ENABLED_PEERS;
+  const opensPerMin = opts.opensPerMin || OPENS_PER_MIN;
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+
+  // peerId -> state. Enabled = has state (owner granted the feed explicitly);
+  // enabling beyond the budget is refused with a named error.
+  const peers = new Map();
+
+  function freshState() {
+    return {
+      epoch: 1,
+      seq: 0,
+      ring: [],            // [{seq, bytes, at, envelope}]
+      ringBytes: 0,
+      streams: [],         // at most one live stream per pair (newest wins)
+      opens: [],           // open timestamps for the per-peer rate
+      counters: { delivered: 0, dropped: 0, replayed: 0, rejected: 0, since: now() },
+      lastCursor: null,
+      lastDropReason: null,
+      lastRejectReason: null,
+    };
+  }
+
+  function state(peerId) { return peers.get(peerId) || null; }
+
+  function enablePeer(peerId) {
+    if (peers.has(peerId)) return peers.get(peerId);
+    if (peers.size >= maxPeers) {
+      const e = new Error('too many peers enabled for the event feed');
+      e.reason = 'peer-budget';
+      throw e;
+    }
+    const st = freshState();
+    peers.set(peerId, st);
+    return st;
+  }
+
+  function disablePeer(peerId) {
+    const st = peers.get(peerId);
+    if (st) closeStreams(st, 'peer-disabled');
+    peers.delete(peerId);
+  }
+
+  function closeStreams(st, reason) {
+    for (const s of st.streams.splice(0)) {
+      try { s.close(reason); } catch (_) { /* best-effort */ }
+    }
+  }
+
+  // Grant/scope change or revocation: the view is dead, not re-filtered.
+  function invalidatePeer(peerId, reason) {
+    const st = peers.get(peerId);
+    if (!st) return;
+    closeStreams(st, reason);
+    st.epoch += 1;
+    st.seq = 0;
+    st.ring = [];
+    st.ringBytes = 0;
+    st.lastCursor = null;
+    log(`event-feed: view reset for peer ${peerId} (${reason})`);
+  }
+
+  // Kill-switch: close everything served, wipe every ring, refuse new opens.
+  function invalidateAll(reason) {
+    for (const [peerId, st] of peers) {
+      closeStreams(st, reason);
+      st.epoch += 1;
+      st.seq = 0;
+      st.ring = [];
+      st.ringBytes = 0;
+      st.lastCursor = null;
+      log(`event-feed: view reset for peer ${peerId} (${reason})`);
+    }
+  }
+
+  function pruneRing(st) {
+    const cutoff = now() - RING_MAX_MS;
+    while (st.ring.length > 0 && (
+      st.ring.length > RING_MAX_EVENTS
+      || st.ringBytes > RING_MAX_BYTES
+      || (st.ring.length > 0 && st.ring[0].at < cutoff && st.ring.length > 1)
+    )) {
+      const dropped = st.ring.shift();
+      st.ringBytes -= dropped.bytes;
+    }
+  }
+
+  // Publish an ALREADY-SCOPED envelope to one peer. The caller applied the ACL
+  // before calling: this function trusts the envelope's peer binding and
+  // refuses frames over the byte cap before they ever enter the ring.
+  function publish(peerId, envelope) {
+    const st = peers.get(peerId);
+    if (!st) return { ok: false, reason: 'peer-not-enabled' };
+    const bytes = Buffer.byteLength(JSON.stringify(envelope), 'utf8');
+    if (bytes > frameMaxBytes) {
+      st.counters.dropped += 1;
+      st.lastDropReason = 'frame-too-large';
+      return { ok: false, reason: 'frame-too-large' };
+    }
+    st.seq += 1;
+    const entry = { seq: st.seq, bytes, at: now(), envelope };
+    st.ring.push(entry);
+    st.ringBytes += bytes;
+    pruneRing(st);
+    st.lastCursor = `${st.epoch}:${st.seq}`;
+
+    if (st.streams.length > 0) {
+      const s = st.streams[st.streams.length - 1]; // newest stream wins the pair
+      if (s.paused) {
+        s.queue.push(entry);
+        s.queueBytes += bytes;
+        if (s.queue.length > LIVE_QUEUE_MAX_FRAMES || s.queueBytes > LIVE_QUEUE_MAX_BYTES) {
+          // Overflow: close and demand a resync, never a silently lossy stream.
+          st.counters.dropped += s.queue.length;
+          st.lastDropReason = 'live-queue-overflow';
+          closeStreams(st, 'resync-required');
+        }
+      } else {
+        try {
+          if (typeof s.filter === 'function' && !s.filter(entry)) {
+            // Narrower stream (cell-only, node-only): not a drop, a scope.
+          } else {
+            const out = s.write(entry);
+            st.counters.delivered += 1;
+            if (out === false) { s.paused = true; }
+          }
+        } catch (_) {
+          closeStreams(st, 'write-error');
+        }
+      }
+    }
+    return { ok: true, seq: st.seq };
+  }
+
+  // Subscribe an SSE response. `after` is the caller's parsed cursor or null.
+  // Returns {ok, epoch} or {ok:false, status, reason}: the ROUTE turns a
+  // refusal into the right HTTP answer before any byte of content flows.
+  function subscribe(peerId, res, after, opts2 = {}) {
+    const st = peers.get(peerId);
+    if (!st) return { ok: false, status: 403, reason: 'feed-not-enabled' };
+
+    // One stream per pair: a reconnection replaces the previous one.
+    const openCut = now() - 60000;
+    st.opens = st.opens.filter((t) => t > openCut);
+    if (st.opens.length >= opensPerMin) {
+      st.counters.rejected += 1;
+      st.lastRejectReason = 'open-rate';
+      return { ok: false, status: 429, reason: 'open-rate' };
+    }
+    st.opens.push(now());
+
+    let replay = [];
+    if (after) {
+      if (after.epoch !== st.epoch) {
+        st.counters.rejected += 1;
+        st.lastRejectReason = 'reset-required';
+        return { ok: false, status: 409, reason: 'reset-required' };
+      }
+      if (after.seq > st.seq) {
+        st.counters.rejected += 1;
+        st.lastRejectReason = 'cursor-future';
+        return { ok: false, status: 409, reason: 'cursor-future' };
+      }
+      // A cursor older than the ring horizon cannot be replayed honestly.
+      const oldest = st.ring.length > 0 ? st.ring[0].seq : st.seq + 1;
+      if (after.seq + 1 < oldest && !(st.ring.length === 0 && after.seq === st.seq)) {
+        st.counters.rejected += 1;
+        st.lastRejectReason = 'reset-required';
+        return { ok: false, status: 409, reason: 'reset-required' };
+      }
+      replay = st.ring.filter((e) => e.seq > after.seq);
+    }
+
+    // Replace any previous stream for this peer BEFORE writing anything: two
+    // live streams for one pair would double-deliver the same events.
+    closeStreams(st, 'replaced');
+
+    const stream = {
+      res,
+      paused: false,
+      queue: [],
+      queueBytes: 0,
+      closed: false,
+      write(entry) {
+        if (stream.closed) return false;
+        st.counters.delivered += 1;
+        return res.write(`id: ${st.epoch}:${entry.seq}\ndata: ${JSON.stringify(entry.envelope)}\n\n`);
+      },
+      queueEntry(entry) {
+        stream.queue.push(entry);
+        stream.queueBytes += entry.bytes;
+      },
+      drain() {
+        stream.paused = false;
+        while (!stream.paused && stream.queue.length > 0) {
+          const entry = stream.queue.shift();
+          stream.queueBytes -= entry.bytes;
+          try {
+            if (stream.write(entry) === false) stream.paused = true;
+          } catch (_) { closeStreams(st, 'write-error'); return; }
+        }
+        if (stream.queue.length > LIVE_QUEUE_MAX_FRAMES || stream.queueBytes > LIVE_QUEUE_MAX_BYTES) {
+          st.counters.dropped += stream.queue.length;
+          st.lastDropReason = 'live-queue-overflow';
+          closeStreams(st, 'resync-required');
+        }
+      },
+      close(reason) {
+        if (stream.closed) return;
+        stream.closed = true;
+        clearInterval(stream.hb);
+        const idx = st.streams.indexOf(stream);
+        if (idx >= 0) st.streams.splice(idx, 1);
+        try { res.end(); } catch (_) { /* the socket may be gone */ }
+        log(`event-feed: stream closed for peer ${peerId} (${reason})`);
+      },
+    };
+    const hb = setInterval(() => {
+      if (stream.closed) { clearInterval(hb); return; }
+      // A heartbeat is also a revoke checkpoint: grants are re-read without
+      // waiting for the next event.
+      if (typeof opts.validatePeer === 'function') {
+        let alive = true;
+        try { alive = opts.validatePeer(peerId) !== false; } catch (_) { alive = false; }
+        if (!alive) { closeStreams(st, 'revoked'); return; }
+      }
+      try {
+        const out = res.write(':hb\n\n');
+        if (out === false) stream.paused = true;
+      } catch (_) { closeStreams(st, 'heartbeat-error'); }
+    }, heartbeatMs);
+    if (typeof hb.unref === 'function') hb.unref();
+    stream.hb = hb;
+    st.streams.push(stream);
+
+    // Atomic replay-to-live: both happen inside this synchronous turn, so no
+    // publish can fall between the last replayed frame and the live hookup.
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-store',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    });
+    res.write('retry: 5000\n\n');
+    if (typeof opts2.filter === 'function') stream.filter = opts2.filter;
+    for (const entry of replay) {
+      if (stream.filter && !stream.filter(entry)) continue;
+      st.counters.replayed += 1;
+      if (stream.write(entry) === false) { stream.paused = true; stream.queueEntry(entry); }
+    }
+    res.on('close', () => { try { stream.close('client-disconnect'); } catch (_) {} });
+    res.on('drain', () => { if (stream.paused) stream.drain(); });
+    // write() returning false on the replay frames left them queued: drain now.
+    if (stream.paused && !stream.closed) stream.drain();
+    return { ok: true, epoch: st.epoch, seq: st.seq };
+  }
+
+  function status(peerId) {
+    const st = peers.get(peerId);
+    if (!st) return null;
+    return {
+      enabled: true,
+      viewEpoch: st.epoch,
+      seq: st.seq,
+      lastCursor: st.lastCursor,
+      ring: { events: st.ring.length, bytes: st.ringBytes },
+      streams: st.streams.length,
+      counters: { ...st.counters },
+      lastDropReason: st.lastDropReason,
+      lastRejectReason: st.lastRejectReason,
+    };
+  }
+
+  function closeAll() {
+    for (const [, st] of peers) closeStreams(st, 'shutdown');
+    if (opts.keepTimers !== true) { /* heartbeats die with their streams */ }
+  }
+
+  return {
+    enablePeer, disablePeer, invalidatePeer, invalidateAll,
+    publish, subscribe, status, closeAll,
+    peerIds: () => [...peers.keys()],
+    enabledCount: () => peers.size,
+  };
+}
+
+module.exports = {
+  createEventFeed,
+  LIMITS: Object.freeze({
+    HEARTBEAT_MS, FRAME_MAX_BYTES, RING_MAX_EVENTS, RING_MAX_BYTES, RING_MAX_MS,
+    LIVE_QUEUE_MAX_FRAMES, LIVE_QUEUE_MAX_BYTES, MAX_ENABLED_PEERS, OPENS_PER_MIN,
+  }),
+};

package/lib/notify/events.js

@@ -1,5 +1,5 @@
 'use strict';
-// Hub SSE per gli eventi UI (notify/ask) — MCP bridge, design §2a.
+// SSE hub for UI events (notify/ask) — MCP bridge.
 // Non esisteva un canale UI-broadcast (i WS sono per-attach PTY, il frame
 // 'files' viaggia solo verso i client attached alla sessione): GET /api/events
 // e' il canale EventSource su cui OGNI vista della UI ascolta notify/ask.

package/lib/notify/notifier.js

@@ -1,7 +1,7 @@
 'use strict';
-// Facciata unica di emissione notifiche (MCP bridge §2): UI (SSE broadcast) +
-// web-push. Riusata dalla route /api/notify, dagli ask (urgency high) e dalla
-// consegna file in outbox — un solo punto che conosce entrambi i canali.
+// Single facade for emitting notifications (MCP bridge): UI (SSE broadcast) +
+// web-push. Reused by the /api/notify route, by the asks (high urgency) and
+// by the outbox file delivery — one point that knows both channels.
 
 function createNotifier({ hub, push }) {
   // frame: {title, body?, urgency?, session?, lang?, url?}. Ritorna {ui, push} (conteggi).

package/lib/notify/push-relay.js

@@ -0,0 +1,240 @@
+'use strict';
+// lib/notify/push-relay.js — OS alert relay for IMPORTED notifications.
+//
+// Only NEW, authorized imported notify envelopes reach the push sender: ask
+// closures and state frames update the UI silently, an ask's first alert
+// travels with its correlated notify, and a snapshot or a replay of an
+// already-known event never rings twice. The (owner, eventId) pair is
+// persisted BEFORE the send — a crash in between may lose an alert, it may
+// never duplicate one.
+//
+// The queue is its own budget, separate from local notifications: 32 alerts
+// or 128 KiB, at most 2 concurrent sends, 10 s per send. Errors are counted,
+// best-effort: a failed push NEVER causes a retry of the SSE stream that
+// already accepted the event. The alert budget (6 per cell per minute,
+// 12 per client per minute) is a dedicated window and urgency never
+// bypasses it.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const QUEUE_MAX_ALERTS = 32;
+const QUEUE_MAX_BYTES = 128 * 1024;
+const MAX_CONCURRENT = 2;
+const SEND_TIMEOUT_MS = 10000;
+const PAYLOAD_MAX_BYTES = 3 * 1024;
+const DEDUP_CAP = 4096;
+const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
+const CELL_ALERTS_PER_MIN = 6;
+const CLIENT_ALERTS_PER_MIN = 12;
+
+function truncateUtf8(str, maxBytes) {
+  const out = [];
+  let bytes = 0;
+  for (const ch of String(str)) {
+    const b = Buffer.byteLength(ch, 'utf8');
+    if (bytes + b > maxBytes) return { text: out.join('') + '…', truncated: true };
+    bytes += b;
+    out.push(ch);
+  }
+  return { text: out.join(''), truncated: false };
+}
+
+// Truncate at a UNICODE boundary (never splitting a code point) and say so.
+function buildPayload(envelope) {
+  const f = envelope.frame || {};
+  const full = typeof f.body === 'string' ? f.body : '';
+  const { text: preview, truncated } = truncateUtf8(full, 200);
+  const where = envelope.scope === 'cell' && envelope.cellId ? envelope.cellId : '';
+  const askId = typeof f.askId === 'string' && f.askId ? f.askId : null;
+  // Local route only: the app decides what to open, the payload never carries a
+  // peer URL. ask= is present only when the source names an ask.
+  const url = `/#owner=${envelope.ownerId}`
+    + (askId ? `&ask=${encodeURIComponent(askId)}` : '')
+    + (where ? `&cell=${encodeURIComponent(where)}` : '');
+  // The FULL body lives in the card (the app holds the imported envelope);
+  // the OS payload carries the preview only.
+  void full;
+  return {
+    title: truncateUtf8(f.title || 'NexusCrew', 120).text,
+    ...(preview ? { body: truncated ? `${preview}…` : preview } : {}),
+    ...(f.lang ? { lang: f.lang } : {}),
+    tag: `nc:${envelope.ownerId}:${envelope.eventId}`,
+    url,
+    ownerId: envelope.ownerId,
+    eventId: envelope.eventId,
+    ...(askId ? { askId } : {}),
+  };
+}
+
+function createPushDedup({ filePath, now = Date.now } = {}) {
+  function load() {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      if (parsed && parsed.seen && typeof parsed.seen === 'object') return parsed;
+    } catch (_) { /* fresh */ }
+    return { seen: {} };
+  }
+  function seenBefore(owner, eventId) {
+    return load().seen[`${owner}:${eventId}`] !== undefined;
+  }
+  // Persist BEFORE the send: the crash window may lose an alert, never
+  // duplicate one.
+  function mark(owner, eventId) {
+    const state = load();
+    state.seen[`${owner}:${eventId}`] = now();
+    const cutoff = now() - DEDUP_TTL_MS;
+    for (const [k, t] of Object.entries(state.seen)) {
+      if (t < cutoff) delete state.seen[k];
+    }
+    const keys = Object.keys(state.seen);
+    if (keys.length > DEDUP_CAP) {
+      for (const k of keys.slice(0, keys.length - DEDUP_CAP)) delete state.seen[k];
+    }
+    try {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
+      fs.renameSync(tmp, filePath);
+    } catch (_) { return false; }
+    return true;
+  }
+  return { seenBefore, mark };
+}
+
+// `send` is the push sender call (pushService.sendToAll wrapped with the
+// timeout). Everything else is queue + budget + counters.
+function createPushRelay({ pushDedup, send, now = Date.now, sendTimeoutMs = SEND_TIMEOUT_MS, log = () => {} } = {}) {
+  const queue = [];
+  let queueBytes = 0;
+  let active = 0;
+  const cellWindow = new Map();
+  const clientWindow = [];
+  const counters = { pushed: 0, dropped: 0, sendFailed: 0, since: now() };
+  // Per-owner view of the same numbers, for the local observability surfaces:
+  // an operator asking about ONE peer should not read the fleet total.
+  const ownerCounters = new Map();
+  function forOwner(ownerId) {
+    const key = ownerId || 'unknown';
+    if (!ownerCounters.has(key)) {
+      ownerCounters.set(key, { pushed: 0, dropped: 0, sendFailed: 0, lastReason: null, since: counters.since });
+    }
+    return ownerCounters.get(key);
+  }
+
+  function budgetAllows(cellId) {
+    const t = now();
+    const cutoff = t - 60000;
+    const clean = (m) => { for (const [k, v] of m) { const kept = v.filter((x) => x > cutoff); if (kept.length) m.set(k, kept); else m.delete(k); } };
+    clean(cellWindow);
+    while (clientWindow.length && clientWindow[0] <= cutoff) clientWindow.shift();
+    const cellKey = cellId || 'node';
+    const perCell = (cellWindow.get(cellKey) || []);
+    if (perCell.length >= CELL_ALERTS_PER_MIN) return false;
+    if (clientWindow.length >= CLIENT_ALERTS_PER_MIN) return false;
+    perCell.push(t); cellWindow.set(cellKey, perCell);
+    clientWindow.push(t);
+    return true;
+  }
+
+  async function flush() {
+    while (active < MAX_CONCURRENT && queue.length > 0) {
+      const item = queue.shift();
+      queueBytes -= item.bytes;
+      active += 1;
+      try {
+        const out = await Promise.race([
+          send(item.payload),
+          new Promise((resolve) => setTimeout(() => resolve({ timeout: true }), sendTimeoutMs)),
+        ]);
+        const own = forOwner(item.payload && item.payload.ownerId);
+        if (out && out.timeout) {
+          counters.sendFailed += 1; own.sendFailed += 1; own.lastReason = 'send-timeout';
+          log('push-relay: send timeout');
+        } else if (out && out.sent > 0) { counters.pushed += out.sent; own.pushed += out.sent; }
+        else { counters.sendFailed += 1; own.sendFailed += 1; own.lastReason = 'send-failed'; }
+      } catch (_) {
+        counters.sendFailed += 1;
+        const own = forOwner(item.payload && item.payload.ownerId);
+        own.sendFailed += 1; own.lastReason = 'send-failed';
+      }
+      active -= 1;
+    }
+  }
+
+  // Consider ONE imported notify envelope. Returns false when nothing was
+  // sent (already known, filtered, out of budget or over the queue caps).
+  function consider(envelope) {
+    if (!envelope || envelope.frame && envelope.frame.type && envelope.frame.type !== 'notify') return false;
+    if (!envelope.eventId || !envelope.ownerId) return false;
+    if (pushDedup.seenBefore(envelope.ownerId, envelope.eventId)) return false;
+    const payload = buildPayload(envelope);
+    const bytes = Buffer.byteLength(JSON.stringify(payload), 'utf8');
+    if (bytes > PAYLOAD_MAX_BYTES) {
+      counters.dropped += 1; const own = forOwner(envelope.ownerId);
+      own.dropped += 1; own.lastReason = 'payload-oversize';
+      return false;
+    }
+    if (!budgetAllows(envelope.cellId)) {
+      counters.dropped += 1; const own = forOwner(envelope.ownerId);
+      own.dropped += 1; own.lastReason = 'alert-budget';
+      return false;
+    }
+    if (queue.length + 1 > QUEUE_MAX_ALERTS || queueBytes + bytes > QUEUE_MAX_BYTES) {
+      counters.dropped += queue.length;
+      const own = forOwner(envelope.ownerId);
+      own.dropped += queue.length; own.lastReason = 'queue-overflow';
+      queue.length = 0; queueBytes = 0;
+      return false; // overflow: the UI resyncs, never a partial alert flood
+    }
+    // Dedup is durable and BEFORE the send.
+    if (!pushDedup.mark(envelope.ownerId, envelope.eventId)) {
+      counters.dropped += 1; counters.lastReason = 'dedup-persist-failed';
+      const own = forOwner(envelope.ownerId);
+      own.dropped += 1; own.lastReason = 'dedup-persist-failed';
+      return false;
+    }
+    queue.push({ payload, bytes });
+    queueBytes += bytes;
+    void flush();
+    return true;
+  }
+
+  // The client server re-emits one flattened event per imported envelope into
+  // the local hub. That is the only place a NEW imported event exists on this
+  // side, so the relay is fed from there: an ask or a closure updates the UI
+  // silently (an ask's first alert travels with its correlated notify), and a
+  // state frame never rings.
+  function considerImported(event) {
+    if (!event || event.type !== 'notify') return false;
+    if (!event.ownerId || !event.eventId) return false;
+    return consider({
+      ownerId: event.ownerId,
+      eventId: event.eventId,
+      scope: event.originCell ? 'cell' : 'node',
+      cellId: event.originCell || null,
+      frame: {
+        type: 'notify', title: event.title, body: event.body, lang: event.lang,
+        ...(event.askId ? { askId: String(event.askId) } : {}),
+      },
+    });
+  }
+
+  // Local, read-only view: counters and reasons only — never an endpoint, a
+  // subscription or a key.
+  function status() {
+    return {
+      queued: queue.length, queueBytes, active,
+      counters: { ...counters },
+      byOwner: Object.fromEntries([...ownerCounters.entries()].map(([k, v]) => [k, {
+        queued: queue.filter((q) => (q.payload && q.payload.ownerId) === k).length,
+        pushed: v.pushed, dropped: v.dropped, sendFailed: v.sendFailed,
+        lastReason: v.lastReason, since: v.since,
+      }])),
+    };
+  }
+
+  return { consider, considerImported, status, buildPayload };
+}
+
+module.exports = { createPushRelay, createPushDedup, buildPayload, truncateUtf8 };

package/lib/notify/push.js

@@ -1,11 +1,11 @@
 'use strict';
-// Web Push per il MCP bridge (design §2b). Chiavi VAPID generate LAZY al primo
-// uso (mai allo startup: i test che creano il server con path isolati non devono
-// scrivere in ~/.nexuscrew) e persistite in <dir>/vapid.json 0600; subscription
-// in <dir>/push.json 0600, dedup per endpoint. Su push fallito 404/410 la
-// subscription viene rimossa (MA non in READONLY: il cleanup e' una scrittura).
-// Il sender e' iniettabile (webpushImpl) cosi' i test non toccano MAI la rete;
-// la chiave PRIVATA non esce da questo modulo.
+// Web Push for the MCP bridge. VAPID keys generated LAZY on first use
+// (never at startup: tests creating the server with isolated paths must not
+// write to ~/.nexuscrew) and persisted in <dir>/vapid.json 0600; subscriptions
+// in <dir>/push.json 0600, dedup by endpoint. On a failed push 404/410 the
+// subscription is removed (NOT in READONLY: the cleanup is a write).
+// The sender is injectable (webpushImpl) so tests NEVER touch the network;
+// the PRIVATE key never leaves this module.
 //
 // da revisione (threat model SSRF): sendNotification fa una richiesta server-side.
 // Ogni endpoint e' https-only, viene risolto sia al subscribe sia immediatamente
@@ -185,7 +185,7 @@ function createPushService(opts = {}) {
   let vapid = null;
   function loadVapid() {
     if (vapid && vapid.publicKey && vapid.privateKey) return vapid;
-    const cur = readJsonSafe(vapidPath); // fail-closed su mode/owner/symlink (F4)
+    const cur = readJsonSafe(vapidPath); // Fail-closed su mode/owner/symlink
     if (typeof cur.publicKey === 'string' && cur.publicKey
       && typeof cur.privateKey === 'string' && cur.privateKey) {
       vapid = { publicKey: cur.publicKey, privateKey: cur.privateKey };