@mmmbuto/nexuscrew 0.9.28 → 0.9.30

package/lib/mcp/server.js

@@ -81,12 +81,12 @@ function companionInstructions() {
 }
 
 // --- identita' cella mittente ------------------------------------------------
-// Ordine delle sorgenti (design §1, INVARIATO): $TMUX presente -> tmux
-// display-message (nome sessione reale); se fallisce/invalida -> fallback env
-// NEXUSCREW_MCP_SESSION; altrimenti null. I tool che RICHIEDONO la sessione
-// restano fail-closed. execFile argv diretto: mai shell.
+// Source order (UNCHANGED): $TMUX present -> tmux display-message (real
+// session name); if it fails/is invalid -> env fallback NEXUSCREW_MCP_SESSION;
+// otherwise null. The tools that REQUIRE the session stay fail-closed.
+// execFile direct argv: never a shell.
 //
-// P0: il nome da tmux si chiede con `-t $TMUX_PANE` — target esplicito al
+// Il nome da tmux si chiede con `-t $TMUX_PANE` — target esplicito al
 // PANE del chiamante, deterministico e indipendente dall'environ ereditato.
 // Senza `-t` il CLI tmux risolve il pane dall'ENVIRON DEL PROCESSO FIGLIO:
 // se quel pane è vivo risponde correttamente, ma se è morto (environ stale,
@@ -95,7 +95,7 @@ function companionInstructions() {
 // Comportamento misurato su tmux 3.4 con `-t`: pane morto -> rc=0 e stdout
 // VUOTO (non un errore): il vuoto è il segnale dello stantio.
 //
-// `resolveIdentity` rende OSSERVABILE la sorgente della risoluzione (P0):
+// `resolveIdentity` rende OSSERVABILE la sorgente della risoluzione:
 // ritorna { session, source, code, envPresence, requiredEnvVars, remediation }
 // senza cambiare la precedenza e senza esporre valori/segreti. `resolveSession`
 // resta il wrapper pubblico Promise<string|null> invariato (compatibilita').
@@ -174,13 +174,13 @@ function resolveIdentity({ env, tmuxBin, execFileImpl }) {
     session: null, source: 'missing', code: codeWhenMissing(),
     envPresence, requiredEnvVars: IDENTITY_ALL_REQUIRED_ENV_VARS, remediation: IDENTITY_REMEDIATION,
   });
-  // P0: pane stantio o non verificabile -> NON attribuire. source 'stale-pane'
+  // Pane stantio o non verificabile -> NON attribuire. source 'stale-pane'
   // nomina il problema; code STALE_PANE (tools.js).
   const stalePane = () => ({
     session: null, source: 'stale-pane', code: IDENTITY_CODE.STALE_PANE,
     envPresence, requiredEnvVars: IDENTITY_ALL_REQUIRED_ENV_VARS, remediation: IDENTITY_REMEDIATION,
   });
-  // P0/R2: tmux e fallback env dicono sessioni DIVERSE entrambe valide:
+  // : tmux e fallback env dicono sessioni DIVERSE entrambe valide:
   // identità ambigua -> NON attribuire (nemmeno il fallback: è parte del
   // conflitto). Il code nomina il mismatch, che INVALID non direbbe.
   const sessionMismatch = () => ({
@@ -190,7 +190,7 @@ function resolveIdentity({ env, tmuxBin, execFileImpl }) {
 
   return new Promise((resolve) => {
     // Precedenza preservata: prima il fallback env valido, poi l'esito negativo
-    // dato (`missing` storico o `stalePane` P0).
+    // Dato (`missing` storico o `stalePane`).
     const settle = (otherwise) => {
       const fb = tryFallback();
       resolve(typeof fb === 'string' ? ok(fb, 'NEXUSCREW_MCP_SESSION') : otherwise());
@@ -217,13 +217,13 @@ function resolveIdentity({ env, tmuxBin, execFileImpl }) {
         // rc=0 e stdout VUOTO. Il vuoto è il segnale dello stantio.
         if (!name) return settle(stalePane);
         if (isValidSession(name)) {
-          // R2: se il fallback env è valido ma dice un'altra sessione, le due
+          // Se il fallback env è valido ma dice un'altra sessione, le due
           // fonti si contraddicono -> ambiguo, non si attribuisce.
           const fb = tryFallback();
           if (typeof fb === 'string' && fb !== name) return resolve(sessionMismatch());
           return resolve(ok(name, 'tmux'));
         }
-        // nome non vuoto ma invalido: precedenza preservata, come da design §1.
+        // non-empty but invalid name: precedence preserved, by design.
         settle(missing);
       });
     } catch (_) {
@@ -618,9 +618,9 @@ function startMcp(opts = {}) {
 
 module.exports = {
   createMcpServer, startMcp, resolveSession, resolveIdentity, normalizeIdentityContext, TOOLS,
-  // V-69: il ramo vl di resolveManagedEngine compone le istruzioni companion
-  // nel file di prompt per-cella — vl non ha client MCP, questo e' l'unica
-  // superficie attraverso cui il testo lo raggiunge.
+  // The vl branch of resolveManagedEngine composes the companion instructions
+  // into the per-cell prompt file — vl has no MCP client, this is the only
+  // surface through which the text reaches it.
   companionInstructions,
   PROTOCOL_FALLBACK, HTTP_TIMEOUT_MS, HTTP_TIMEOUT_CODE, HTTP_UNREACHABLE_CODE, transportError,
   IDENTITY_CONTEXT_MISSING, IDENTITY_CONTEXT_UNVERIFIED, IDENTITY_CONTEXT_FROM_MISMATCH,

package/lib/mcp/tools.js

@@ -30,7 +30,7 @@ function argString(args, key, { required = false, max = 4096 } = {}) {
   return v;
 }
 
-// Codici stabili di identita' MCP (contratto P0). Valori EXACT, non sensibili,
+// Codici stabili di identita' MCP (contratto). Valori EXACT, non sensibili,
 // usati sia nella diagnostica read-only (`nc_identity`) sia nel messaggio umano
 // dei tool identity-gated (isError=true preservato dal server). Non espongono
 // valori/env/sessioni: solo la categoria del problema.
@@ -38,10 +38,10 @@ const IDENTITY_CODE = Object.freeze({
   OK: 'OK',
   MISSING: 'NEXUSCREW_MCP_IDENTITY_MISSING',
   INVALID: 'NEXUSCREW_MCP_IDENTITY_INVALID',
-  // P0: il pane del chiamante non esiste più (o TMUX_PANE è assente/malformato):
+  // Il pane del chiamante non esiste più (o TMUX_PANE è assente/malformato):
   // l'identità non viene attribuita via tmux.
   STALE_PANE: 'NEXUSCREW_MCP_IDENTITY_STALE_PANE',
-  // P0/R2: tmux e NEXUSCREW_MCP_SESSION sono entrambi validi ma dicono sessioni
+  // : tmux e NEXUSCREW_MCP_SESSION sono entrambi validi ma dicono sessioni
   // diverse: identità ambigua, non si attribuisce nessuna delle due.
   SESSION_MISMATCH: 'NEXUSCREW_MCP_IDENTITY_SESSION_MISMATCH',
   // una fonte verified (NEXUSCREW_VERIFIED_*) presente ma non
@@ -303,7 +303,7 @@ function vlOwnerPath(owner, leaf = '') {
 }
 
 // --- definizione tool (prefisso nc_ anti-collisione) ---------------------------
-// annotations.readOnlyHint:true sui tool che non mutano nulla (§1).
+// annotations.readOnlyHint:true on the tools that mutate nothing.
 const TOOLS = [
   {
     name: 'nc_notify',
@@ -920,7 +920,7 @@ const TOOLS = [
       return { receipt };
     },
   },
-  // --- lease Live del child (fetta 2b, contratto rev1 B5) ----------------------
+  // -- lease Live del child (fetta 2b, contratto rev1) ----------------------
   // Tre metodi DISTINTI perche' i valori di ritorno non mentono l'uno con l'altro:
   // solo register puo' rispondere {status:'pending'} (join non ancora tracciato);
   // refresh su registration viva risponde {status:'live', proof} e non ha stati

package/lib/nodes/access-presets.js

@@ -0,0 +1,258 @@
+'use strict';
+
+// Access presets for paired peers.
+//
+// A preset is a vector of grants written in ONE validated write on the node
+// that owns the resources. There is no persistent `role` field: the label
+// (`admin`, `user`, `nexushost`, `custom`, `unconfigured`) is DERIVED from the
+// effective grants, and request handlers check grants, never the label.
+//
+// The owner node decides what a peer may do with its own resources. A grant
+// that is missing or malformed is denied, and a record written before these
+// fields existed stays denied until an explicit migration sets them: being
+// paired is not, by itself, a permission.
+
+const MAX_CELLS = 128;
+const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
+
+const CELL_VISIBILITY = Object.freeze(['all', 'selected', 'none']);
+
+// Grants owned by the local node towards one peer.
+const BOOLEAN_GRANTS = Object.freeze([
+  'eventsAccess',
+  'nodeEventsAccess',
+  'askReplyAccess',
+  'filesReadAccess',
+  'liveHostAccess',
+  'panelAccess',
+  'peerOperatorAccess',
+]);
+
+// `eventsReceive` is the receiving client's local choice, so it is excluded
+// from every preset: applying a preset never toggles who receives events.
+const EXCLUDED_GRANTS = Object.freeze(['eventsReceive']);
+
+const GRANT_FIELDS = Object.freeze(['cellVisibility', 'cells', ...BOOLEAN_GRANTS]);
+
+// Provenance marker of an explicitly configured vector. It is not a grant and
+// never a role: it only separates "set on purpose" from "defaulted".
+const CONFIGURED_MARKER = 'accessConfigured';
+
+const ADMIN_GRANTS = Object.freeze({
+  cellVisibility: 'all',
+  eventsAccess: true,
+  nodeEventsAccess: true,
+  askReplyAccess: true,
+  filesReadAccess: true,
+  liveHostAccess: true,
+  panelAccess: true,
+  peerOperatorAccess: true,
+});
+
+const USER_GRANTS = Object.freeze({
+  cellVisibility: 'all',
+  eventsAccess: true,
+  nodeEventsAccess: true,
+  askReplyAccess: false,
+  filesReadAccess: true,
+  liveHostAccess: false,
+  panelAccess: false,
+  peerOperatorAccess: false,
+});
+
+const NEXUSHOST_GRANTS = Object.freeze({
+  cellVisibility: 'none',
+  eventsAccess: false,
+  nodeEventsAccess: false,
+  askReplyAccess: false,
+  filesReadAccess: false,
+  liveHostAccess: false,
+  panelAccess: false,
+  peerOperatorAccess: false,
+});
+
+const PRESETS = Object.freeze({
+  admin: ADMIN_GRANTS,
+  user: USER_GRANTS,
+  nexushost: NEXUSHOST_GRANTS,
+});
+
+const PRESET_NAMES = Object.freeze(Object.keys(PRESETS));
+
+// Every grant denied: what an unknown peer gets.
+const DENIED_GRANTS = Object.freeze({
+  cellVisibility: 'none',
+  ...Object.fromEntries(BOOLEAN_GRANTS.map((k) => [k, false])),
+});
+
+function isPlainObject(v) {
+  return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isCellId(v) {
+  return typeof v === 'string' && CELL_ID_RE.test(v);
+}
+
+// The admin vector is all-or-nothing: live hosting is an administrative act
+// on the owner's own host, so it is granted only together with the complete
+// admin set. A granular edit that keeps live hosting while dropping any other
+// admin grant is refused.
+function isCompleteAdminVector(g) {
+  if (!isPlainObject(g)) return false;
+  if (g.cellVisibility !== 'all') return false;
+  if (Array.isArray(g.cells) && g.cells.length !== 0) return false;
+  return BOOLEAN_GRANTS.every((k) => g[k] === true);
+}
+
+// Validates a grant vector. Returns { ok, errors }: `ok` means the vector is
+// complete and coherent, so a label may be derived from it. A vector that is
+// not ok is DENIED by callers; it is never completed with defaults.
+function validateGrants(input) {
+  const errors = [];
+  if (!isPlainObject(input)) {
+    return { ok: false, errors: ['grants must be an object'] };
+  }
+  for (const key of Object.keys(input)) {
+    if (key === 'role') {
+      errors.push('role is not a grant: the label is derived from the grants');
+    } else if (EXCLUDED_GRANTS.includes(key)) {
+      errors.push(`${key} is a local client choice and is not part of a preset`);
+    } else if (!GRANT_FIELDS.includes(key)) {
+      errors.push(`unknown grant field: ${key}`);
+    }
+  }
+
+  if (!CELL_VISIBILITY.includes(input.cellVisibility)) {
+    errors.push('cellVisibility must be one of all|selected|none');
+  }
+
+  let cells = [];
+  if (input.cells !== undefined) {
+    if (!Array.isArray(input.cells)) {
+      errors.push('cells must be an array');
+    } else if (input.cells.length > MAX_CELLS) {
+      errors.push(`cells must hold at most ${MAX_CELLS} entries`);
+    } else if (!input.cells.every(isCellId)) {
+      errors.push('cells entries must be cell names');
+    } else if (new Set(input.cells).size !== input.cells.length) {
+      errors.push('cells must not repeat an entry');
+    } else {
+      cells = input.cells;
+    }
+  }
+  if (input.cellVisibility === 'selected' && cells.length === 0) {
+    errors.push('cellVisibility selected needs at least one cell');
+  }
+  if ((input.cellVisibility === 'all' || input.cellVisibility === 'none') && cells.length > 0) {
+    errors.push('cells are allowed only with cellVisibility selected');
+  }
+
+  for (const key of BOOLEAN_GRANTS) {
+    if (!(key in input)) errors.push(`missing grant: ${key}`);
+    else if (typeof input[key] !== 'boolean') errors.push(`grant must be a boolean: ${key}`);
+  }
+
+  if (input.liveHostAccess === true && !isCompleteAdminVector(input)) {
+    errors.push('liveHostAccess requires the complete admin grant set');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+// A record is configured only when its grant vector is complete and coherent.
+// Records written before these fields existed, or damaged ones, are denied.
+function isConfigured(input) {
+  return validateGrants(input).ok;
+}
+
+function sameBooleans(a, b) {
+  return BOOLEAN_GRANTS.every((k) => a[k] === b[k]);
+}
+
+// Derives the label from the effective grants. `custom` means a coherent
+// vector that matches no preset; `unconfigured` means the vector is not
+// complete, so no preset may be inferred from it.
+function deriveLabel(input) {
+  if (!isConfigured(input)) return 'unconfigured';
+  if (sameBooleans(input, ADMIN_GRANTS) && input.cellVisibility === 'all') return 'admin';
+  if (sameBooleans(input, NEXUSHOST_GRANTS) && input.cellVisibility === 'none') return 'nexushost';
+  // The owner may narrow the visible cells of a user peer without granting
+  // anything new, so any of the three visibility values still reads `user`.
+  if (sameBooleans(input, USER_GRANTS) && CELL_VISIBILITY.includes(input.cellVisibility)) return 'user';
+  return 'custom';
+}
+
+// Returns a copy of the peer record with the grants of the named preset.
+// The input is never mutated; `role` is dropped, because it is not a field
+// that this model persists.
+function applyPreset(peer, name) {
+  if (!isPlainObject(peer)) throw new Error('peer must be an object');
+  if (!Object.prototype.hasOwnProperty.call(PRESETS, name)) {
+    throw new Error(`unknown preset: ${name}`);
+  }
+  const out = { ...peer };
+  delete out.role;
+  const preset = PRESETS[name];
+  // Applying a preset IS the explicit act: the record is marked as configured
+  // so a legacy peer with defaulted (denied) grants is never mistaken for a
+  // deliberate vector that denies everything.
+  out.accessConfigured = true;
+  out.cellVisibility = preset.cellVisibility;
+  if (preset.cellVisibility === 'selected') out.cells = [...(preset.cells || [])];
+  else delete out.cells;
+  for (const key of BOOLEAN_GRANTS) out[key] = preset[key];
+  return out;
+}
+
+// Extracts the grant vector from a peer record. An unconfigured record yields
+// every grant denied.
+function grantsOf(peer) {
+  if (!isPlainObject(peer)) return { configured: false, label: 'unconfigured', grants: { ...DENIED_GRANTS } };
+  const grants = {};
+  grants.cellVisibility = peer.cellVisibility;
+  if (peer.cells !== undefined) grants.cells = peer.cells;
+  for (const key of BOOLEAN_GRANTS) grants[key] = peer[key];
+  // A record is configured only when its vector is coherent AND the vector was
+  // set explicitly. Grants alone cannot tell a legacy record (everything
+  // defaulted to denied) from a deliberate vector that denies everything.
+  const configured = peer.accessConfigured === true && isConfigured(grants);
+  return {
+    configured,
+    label: configured ? deriveLabel(grants) : 'unconfigured',
+    grants: configured ? grants : { ...DENIED_GRANTS },
+  };
+}
+
+
+// Read view of ONE peer for listing endpoints and the settings UI: the
+// derived label, the configured marker and the EFFECTIVE grant vector. The
+// vector is flat and always complete (denied for records that are not
+// configured), so a caller never has to guess defaults and no token or
+// secret is ever included: grants are decisions, not credentials.
+function accessView(peer) {
+  const view = grantsOf(peer);
+  const access = { cellVisibility: view.grants.cellVisibility };
+  for (const key of BOOLEAN_GRANTS) access[key] = view.grants[key] === true;
+  return { accessLabel: view.label, accessConfigured: view.configured, access };
+}
+
+module.exports = {
+  ADMIN_GRANTS,
+  BOOLEAN_GRANTS,
+  CELL_VISIBILITY,
+  CONFIGURED_MARKER,
+  DENIED_GRANTS,
+  EXCLUDED_GRANTS,
+  GRANT_FIELDS,
+  NEXUSHOST_GRANTS,
+  PRESETS,
+  PRESET_NAMES,
+  USER_GRANTS,
+  accessView,
+  applyPreset,
+  deriveLabel,
+  grantsOf,
+  isCompleteAdminVector,
+  isConfigured,
+  validateGrants,
+};

package/lib/nodes/commands.js

@@ -19,6 +19,7 @@ const tunnel = require('./tunnel.js');
 const reversePool = require('./reverse-pool.js');
 const topologyCache = require('./topology-cache.js');
 const inventory = require('./inventory.js');
+const accessPresets = require('./access-presets.js');
 const federation = require('../proxy/federation.js');
 const { resolvePaths, DEFAULT_PORT } = require('../cli/url.js');
 
@@ -248,6 +249,63 @@ function nodesList(opts) {
   return { code: 0, nodes, peers: visiblePeers };
 }
 
+// --- Event feed observability -------------------------------------------------
+// Best-effort LOCAL read of the running server's feed diagnostics. The CLI
+// never reads runtime files for this: if the local server is unreachable it
+// says so explicitly instead of reporting zero deliveries.
+// One line for the OS alert relay of that peer: same local diagnostics payload,
+// counters and last reason only. A peer nobody tried to alert stays honest with
+// zeros instead of disappearing.
+function relayLineFor(body, peerNodeId) {
+  const section = (body && body.pushRelay) || {};
+  const own = (section.byOwner && section.byOwner[peerNodeId]) || {};
+  const last = own.lastReason ? ` · ultimo motivo ${own.lastReason}` : '';
+  return `relay:     avvisi OS in coda ${own.queued || 0} · inviati ${own.pushed || 0} · scartati ${own.dropped || 0} · errori ${own.sendFailed || 0}${last}`;
+}
+
+function feedLinesFor(diag, peerNodeId) {
+  if (!diag || diag.ok !== true) {
+    return [`feed:      diagnostica non disponibile (${(diag && diag.reason) || 'sconosciuto'}) — il server locale non risponde`];
+  }
+  const entry = (diag.body && Array.isArray(diag.body.peers) ? diag.body.peers : [])
+    .find((p) => p.nodeId === peerNodeId);
+  if (!entry) return ['feed:      nessuna vista per questo peer'];
+  const enabled = diag.body.enabled === true;
+  const counters = (entry.feed && entry.feed.counters) || {};
+  const lastProblem = (entry.feed && (entry.feed.lastDropReason || entry.feed.lastRejectReason)) || 'none';
+  const grants = entry.grants || {};
+  return [
+    // The kill-switch state is its OWN line: it is the operator's first
+    // question when the feed is silent.
+    `feed:      kill-switch ${enabled ? 'attivo (feed abilitato)' : 'OFF: feed disabilitato'} · revision ${entry.accessRevision} · label ${entry.accessLabel}`,
+    `feed:      grant events=${grants.eventsAccess === true ? 'on' : 'off'} node-events=${grants.nodeEventsAccess === true ? 'on' : 'off'} · scope celle ${grants.cellVisibility || 'none'}${Array.isArray(grants.cells) && grants.cells.length ? ` (${grants.cells.join(', ')})` : ''}`,
+    `feed:      cursore ${(entry.feed && entry.feed.lastCursor) || '-'} · stream ${(entry.feed && entry.feed.streams) || 0} · ultimo mancato: ${lastProblem}`,
+    `feed:      contatori delivered ${(counters.delivered || 0)} · dropped ${(counters.dropped || 0)} · replayed ${(counters.replayed || 0)} · rejected ${(counters.rejected || 0)}`,
+    relayLineFor(diag.body, peerNodeId),
+  ];
+}
+
+async function fetchFeedDiagnostics(opts = {}) {
+  let port = Number(opts.localAppPort) || null;
+  if (!port && opts.configPath) {
+    try { port = Number(JSON.parse(fs.readFileSync(opts.configPath, 'utf8')).port) || null; } catch (_) { port = null; }
+  }
+  let token = '';
+  try { token = fs.readFileSync(opts.tokenPath, 'utf8').trim(); } catch (_) { return { ok: false, reason: 'no-token' }; }
+  if (!port) return { ok: false, reason: 'no-port' };
+  try {
+    // The local diagnostics live under the authenticated API mount: without
+    // the /api prefix the CLI would read the static handler and report the
+    // server as unreachable while it is answering fine.
+    const r = await (opts.fetchImpl || fetch)(`http://127.0.0.1:${port}/api/diagnostics/events`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(1500),
+    });
+    if (!r.ok) return { ok: false, reason: `http-${r.status}` };
+    return { ok: true, body: await r.json() };
+  } catch (_) { return { ok: false, reason: 'unreachable' }; }
+}
+
 function nodesInspect(opts) {
   const log = opts.log || console.log;
   const out = loadPeerInventory(opts);
@@ -273,11 +331,46 @@ function nodesInspect(opts) {
       const cells = Array.isArray(peer.cells) ? peer.cells : [];
       log(`celle:     ${cells.length ? cells.join(', ') : 'nessuna (elenco vuoto)'} (scope: selected)`);
     }
+    // Effective federated access: the label is DERIVED from the grants, and a
+    // record whose grants were never set says so instead of showing a preset
+    // inferred from defaults.
+    if (peer.kind === 'direct') {
+      const view = accessPresets.grantsOf(peer);
+      log(`accesso:   ${view.label}`);
+      log(`grant:     ${ACCESS_GRANT_KEYS.map((key) => `${key}=${view.grants[key] ? 'on' : 'off'}`).join(' ')}`);
+      log(`scope:     celle ${view.grants.cellVisibility}`);
+      for (const line of feedLinesFor(opts.feedDiagnostics, peer.nodeId)) log(line);
+    }
     log(`azioni:    ${Object.keys(peer.actions || {}).filter((key) => peer.actions[key]).join(', ')}`);
   }
   return { code: 0, peer: found.peer };
 }
 
+// --- Federated access grants -------------------------------------------------
+// The grant vector of a peer is set on the node that OWNS the resources, in one
+// validated write. The label (admin/user/nexushost/custom) is derived from the
+// grants; nothing here stores or reads a role.
+const ACCESS_GRANT_KEYS = ['eventsAccess', 'nodeEventsAccess', 'askReplyAccess', 'filesReadAccess', 'peerOperatorAccess'];
+const ACCESS_EDIT_KEYS = new Set(['accessRole', ...ACCESS_GRANT_KEYS]);
+
+const ACCESS_VECTOR_FIELDS = ['cellVisibility', 'cells', 'panelAccess', 'liveHostAccess'];
+
+// The prospective vector of a peer after applying `overrides`. It covers every
+// field the invariants talk about, so a granular edit cannot leave the record
+// in a state the preset validator would refuse (live hosting without the
+// complete admin set being the case that matters).
+function accessVectorFrom(peer, overrides) {
+  const visibility = Object.hasOwn(overrides, 'cellVisibility') ? overrides.cellVisibility : peer.cellVisibility;
+  const vector = { cellVisibility: visibility };
+  const cells = Object.hasOwn(overrides, 'cells') ? overrides.cells : peer.cells;
+  if (visibility === 'selected') vector.cells = Array.isArray(cells) ? cells : [];
+  const all = [...ACCESS_GRANT_KEYS, 'panelAccess', 'liveHostAccess'];
+  for (const key of all) {
+    vector[key] = Object.hasOwn(overrides, key) ? overrides[key] === true : peer[key] === true;
+  }
+  return vector;
+}
+
 function nodesEdit(opts) {
   const log = opts.log || console.log;
   if (isReadonly(opts)) { log('nodes edit: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
@@ -295,9 +388,12 @@ function nodesEdit(opts) {
   // ai PANNELLI di questo nodo, non chi ha aperto il tunnel — quindi vale in
   // entrambe le direzioni. `liveHostAccess` e' identica: riguarda chi puo'
   // designare la cella ospite Live di QUESTO nodo, non chi ha aperto il tunnel.
+  // eventsReceive is the node's OWN choice to import a peer's feed: it is a
+  // local client decision in BOTH directions and never part of the owner's
+  // grant presets.
   const allowed = node.direction === 'inbound'
-    ? new Set(['label', 'visibility', 'selected', 'cellVisibility', 'cells', 'panelAccess', 'liveHostAccess'])
-    : new Set(['label', 'ssh', 'sshPort', 'autostart', 'cellVisibility', 'cells', 'panelAccess', 'liveHostAccess']);
+    ? new Set(['label', 'visibility', 'selected', 'cellVisibility', 'cells', 'panelAccess', 'liveHostAccess', 'accessRole', 'eventsReceive', ...ACCESS_GRANT_KEYS])
+    : new Set(['label', 'ssh', 'sshPort', 'autostart', 'cellVisibility', 'cells', 'panelAccess', 'liveHostAccess', 'accessRole', 'eventsReceive', ...ACCESS_GRANT_KEYS]);
   const keys = Object.keys(supplied);
   const invalid = keys.find((key) => !allowed.has(key));
   if (invalid) {
@@ -308,6 +404,10 @@ function nodesEdit(opts) {
     log('nodes edit: panelAccess vuole un booleano');
     return { code: 1, reason: 'invalid-panel-access' };
   }
+  if (Object.hasOwn(supplied, 'eventsReceive') && typeof supplied.eventsReceive !== 'boolean') {
+    log('nodes edit: eventsReceive vuole un booleano');
+    return { code: 1, reason: 'invalid-events-receive' };
+  }
   if (Object.hasOwn(supplied, 'liveHostAccess') && typeof supplied.liveHostAccess !== 'boolean') {
     log('nodes edit: liveHostAccess vuole un booleano');
     return { code: 1, reason: 'invalid-live-host-access' };
@@ -342,9 +442,73 @@ function nodesEdit(opts) {
   // ricostruisce il nodo da zero.
   if (Object.hasOwn(patch, 'cellVisibility') && patch.cellVisibility !== 'selected') patch.cells = undefined;
 
+  const accessRequested = keys.some((key) => ACCESS_EDIT_KEYS.has(key));
+  const touchesVector = keys.some((key) => ACCESS_VECTOR_FIELDS.includes(key));
+  // A peer whose grants were never configured keeps its historical behaviour
+  // for panel/live flags; once a vector IS configured, every edit of that
+  // vector passes through the same validator and the same single write.
+  const enforceVector = accessRequested || (touchesVector && node.accessConfigured === true);
+  let accessVector = null;
+  if (enforceVector) {
+    const hasRole = Object.hasOwn(supplied, 'accessRole');
+    const granular = ACCESS_GRANT_KEYS.filter((key) => Object.hasOwn(supplied, key));
+    if (hasRole && granular.length > 0) {
+      log('nodes edit: --access-role e i grant granulari non si combinano nella stessa richiesta');
+      return { code: 1, reason: 'preset-and-grants' };
+    }
+    for (const key of granular) {
+      if (typeof supplied[key] !== 'boolean') {
+        log(`nodes edit: ${key} vuole un booleano`);
+        return { code: 1, reason: 'invalid-grant' };
+      }
+    }
+    if (hasRole) {
+      if (typeof supplied.accessRole !== 'string' || !accessPresets.PRESET_NAMES.includes(supplied.accessRole)) {
+        log(`nodes edit: access-role non valido (atteso: ${accessPresets.PRESET_NAMES.join('|')})`);
+        return { code: 1, reason: 'invalid-access-role' };
+      }
+      accessVector = { ...accessPresets.PRESETS[supplied.accessRole] };
+    } else if (!accessRequested && touchesVector) {
+      // Panel/live/scope edit on a configured peer: same vector, same rules.
+      accessVector = accessVectorFrom(node, supplied);
+    } else {
+      // A granular edit only refines a vector that was set explicitly: a peer
+      // whose grants were never configured stays denied, and a partial edit
+      // must not promote it.
+      if (node.accessConfigured !== true) {
+        log('nodes edit: peer non configurato — applica prima un preset (--access-role)');
+        return { code: 1, reason: 'access-not-configured' };
+      }
+      accessVector = accessVectorFrom(node, supplied);
+    }
+    const check = accessPresets.validateGrants(accessVector);
+    if (!check.ok) {
+      log(`nodes edit: concessioni rifiutate — ${check.errors.join('; ')}`);
+      return { code: 1, reason: 'invalid-grants' };
+    }
+    for (const key of [...ACCESS_EDIT_KEYS, ...ACCESS_VECTOR_FIELDS]) delete patch[key];
+  }
+
   let next;
-  try { next = store.updateNode(st, node.name, patch); }
-  catch (e) { log(`nodes edit: ${e.message}`); return { code: 1, reason: 'invalid-patch' }; }
+  if (enforceVector) {
+    // One validated read-modify-write against the policy revision: a concurrent
+    // edit loses the race and rereads instead of overwriting it.
+    const expected = Number.isInteger(opts.expectedRevision) ? opts.expectedRevision : store.accessRevisionOf(st);
+    let res;
+    try {
+      res = store.setPeerAccessGrantsCas({
+        filePath: nodesPath, name: node.name, grants: accessVector, expectedRevision: expected, extraPatch: patch,
+      });
+    } catch (e) { log(`nodes edit: ${e.message}`); return { code: 1, reason: 'invalid-patch' }; }
+    if (!res.ok) {
+      log(`nodes edit: revision delle concessioni superata (attuale ${res.revision}) — rileggi e riprova`);
+      return { code: 1, reason: 'revision-conflict', revision: res.revision };
+    }
+    next = store.loadStoreStrict(nodesPath);
+  } else {
+    try { next = store.updateNode(st, node.name, patch); }
+    catch (e) { log(`nodes edit: ${e.message}`); return { code: 1, reason: 'invalid-patch' }; }
+  }
 
   const transportChanged = node.direction === 'outbound'
     && ['ssh', 'sshPort'].some((key) => Object.hasOwn(patch, key));
@@ -377,6 +541,33 @@ function nodesEdit(opts) {
   return { code: 0, name: node.name, node: edited, restarted: wasUp };
 }
 
+// --- nodes access: read-only inventory --------------------------------------
+// Shows what every peer may currently do on this node, with the revision of
+// the policy. Peers whose grants were never configured are listed as such:
+// they are the ones an explicit migration has to set, and nothing promotes
+// them by name or by age of pairing.
+function nodesAccess(opts = {}) {
+  const log = opts.log || console.log;
+  const { nodesPath } = resolveNodePaths(opts);
+  let st;
+  try { st = store.loadStoreStrict(nodesPath); }
+  catch (e) { log(`nodes access: ${e.message}`); return { code: 1, reason: 'store invalido', status: e.status || 500 }; }
+  const view = store.accessInventory(st);
+  const legacy = view.peers.filter((peer) => !peer.configured);
+  if (opts.json) {
+    log(JSON.stringify({ revision: view.revision, peers: view.peers, unconfigured: legacy.map((p) => p.name) }, null, 2));
+    return { code: 0, ...view, unconfigured: legacy.map((p) => p.name) };
+  }
+  log(`revision concessioni: ${view.revision}`);
+  if (view.peers.length === 0) log('nessun peer diretto');
+  for (const peer of view.peers) {
+    log(`${peer.name}${peer.nodeId ? ` (${peer.nodeId})` : ''}: ${peer.label}`);
+    log(`  ${ACCESS_GRANT_KEYS.map((key) => `${key}=${peer.grants[key] ? 'on' : 'off'}`).join(' ')} · celle ${peer.grants.cellVisibility}`);
+  }
+  if (legacy.length > 0) log(`da configurare esplicitamente (${legacy.length}): ${legacy.map((p) => p.name).join(', ')}`);
+  return { code: 0, ...view, unconfigured: legacy.map((p) => p.name) };
+}
+
 // --- nodes remove ----------------------------------------------------------
 function nodesRemove(opts) {
   const log = opts.log || console.log;
@@ -683,6 +874,9 @@ function nodesSetToken(opts) {
 }
 
 module.exports = {
+  fetchFeedDiagnostics, feedLinesFor,
+
+  nodesAccess, ACCESS_GRANT_KEYS,
   nodesAdd, nodesList, nodesInspect, nodesEdit, nodesRemove, nodesTest, nodesTestAll,
   nodesUp, nodesDown, nodesRestart, nodesSetToken,
   // helper esposti per test/riuso