@mmmbuto/nexuscrew 0.9.29 → 0.9.30

package/lib/cli/commands.js

@@ -1,5 +1,5 @@
 'use strict';
-// Minimal public CLI plus internal service/MCP entry points. [M6][R1]
+// Minimal public CLI plus internal service/MCP entry points.
 // serve = foreground HTTP (+ --pidfile lifecycle su Termux/manuale).
 // start/stop/status = per-platform: linux (systemctl --user), mac (launchctl),
 // termux (nohup serve --pidfile + pidfile verificato; status boot-script vs running).
@@ -69,6 +69,10 @@ Usage:
   nexuscrew nodes share <name|nodeId> on|off [--json]
   nexuscrew nodes panel <name|nodeId> on|off
   nexuscrew nodes live-host <name|nodeId> on|off
+  nexuscrew nodes edit <name|nodeId> --access-role admin|user|nexushost
+  nexuscrew nodes edit <name|nodeId> --events-access on|off [...grant flags]
+  nexuscrew nodes edit <name|nodeId> --events-receive on|off
+  nexuscrew nodes access [--json]
   nexuscrew nodes invite --ssh TARGET [--ssh-port PORT] [--name SLUG]
                          [--label TEXT] [--json]
   printf '%s' "$PAIRING_URL" | nexuscrew nodes pair|join
@@ -87,7 +91,7 @@ Lifecycle semantics:
 
 const CLI_VALUE_FLAGS = new Set([
   'label', 'ssh', 'ssh-port', 'autostart', 'visibility', 'selected',
-  'name', 'local-name', 'local-label', 'identity-file', 'port', 'dir',
+  'name', 'local-name', 'local-label', 'identity-file', 'port', 'dir', 'events-receive',
 ]);
 
 // valueFlags (Set|array opzionale): flag che consumano il token successivo nella
@@ -221,7 +225,7 @@ function quickSummary(result, opts = {}) {
   log('check   nexuscrew doctor');
 }
 
-// Ruoli client/node dal config.json (default entrambi off — B0 li popola dal wizard UI).
+// Ruoli client/node dal config.json (default entrambi off — li popola dal wizard UI).
 function readRoles(configPath) {
   try {
     const c = JSON.parse(fs.readFileSync(configPath, 'utf8'));
@@ -791,8 +795,8 @@ function url(opts = {}) {
   return { url: full, port, hasToken: !!token };
 }
 
-// token rotate (§4b(3)): scrittura atomica nuovo token + invalidazione reale delle
-// sessioni attive (restart se il service e' attivo). Il nuovo token NON si stampa.
+// Token rotation: atomic write of the new token plus real invalidation of the
+// active sessions (service restart when running). The new token is never printed.
 function tokenRotate(opts = {}) {
   const log = opts.log || console.log;
   const platform = opts.platform || detectPlatform();
@@ -1017,7 +1021,7 @@ function update(opts = {}) {
   return { updated: true, running, restarted: running, bootDefinitions: healed, code: 0 };
 }
 
-// B4.3 — fleet-boot companion: avvia le celle boot:true del provider selezionato.
+// Fleet boot companion: starts the boot:true cells of the selected provider.
 // dispatch e' sync (bin/nexuscrew.js non fa await), quindi runFleetBoot (async)
 // viene lanciato e il processo tenuto vivo (keepAlive) finche' non termina, poi
 // esce col code risultante. runFleetBoot e' la unit testabile (no process.exit);
@@ -1039,7 +1043,7 @@ async function runFleetBoot(opts = {}) {
   }
 
   // builtin: up() per ogni cella boot:true. READONLY fa fallire le up con 403 ->
-  // raccolte in failed[] -> exit 1 (nessun short-circuit speciale, design §9d).
+  // collected in failed[] -> exit 1 (no special short-circuit by design).
   const res = await bootCells(sel.fleet, { log });
   log(`fleet-boot: ${res.started.length} started, ${res.skipped.length} skipped, ${res.failed.length} failed`);
   for (const f of res.failed) log(`  failed: ${f.cell} — ${f.reason}`);
@@ -1105,12 +1109,16 @@ async function dispatchNodes(rest, flags, opts = {}) {
   if (sub === 'list') return { code: nodesCmds.nodesList({
     ...opts, log, json: flags.json === true, direct: flags.direct === true,
   }).code };
-  if (sub === 'inspect' || sub === 'show') return { code: nodesCmds.nodesInspect({ ...opts, log, ref, json: flags.json === true }).code };
+  if (sub === 'inspect' || sub === 'show') {
+    const feedDiagnostics = await nodesCmds.fetchFeedDiagnostics(opts);
+    return { code: (await nodesCmds.nodesInspect({ ...opts, log, ref, json: flags.json === true, feedDiagnostics })).code };
+  }
   if (sub === 'doctor') {
     const view = nodesCmds.loadPeerInventory(opts);
     let peers = view.nodes;
+    const feedDiagnostics = await nodesCmds.fetchFeedDiagnostics(opts);
     if (ref) {
-      const inspected = nodesCmds.nodesInspect({ ...opts, log: () => {}, ref });
+      const inspected = await nodesCmds.nodesInspect({ ...opts, log: () => {}, ref });
       if (inspected.code !== 0) { log(`nodes doctor: nodo sconosciuto "${ref}"`); return { code: 1 }; }
       peers = [inspected.peer];
     }
@@ -1130,7 +1138,15 @@ async function dispatchNodes(rest, flags, opts = {}) {
     }
     if (flags.json === true) log(JSON.stringify({ nodeId: view.nodeId, checks }, null, 2));
     else if (checks.length === 0) log('nodes doctor: nessun peer diretto');
-    else for (const check of checks) log(`${check.name}: ${check.ok ? 'OK' : 'KO'} — ${check.result}${check.detail ? ` · ${check.detail}` : ''}`);
+    else for (const check of checks) {
+      log(`${check.name}: ${check.ok ? 'OK' : 'KO'} — ${check.result}${check.detail ? ` · ${check.detail}` : ''}`);
+      // Feed section per direct peer: kill-switch, cursor, last failure,
+      // counters for observability. Read-only, no secrets.
+      const peer = peers.find((p) => (p.nodeId || null) === (check.nodeId || null) && p.name === check.name);
+      if (peer && peer.kind === 'direct') {
+        for (const line of nodesCmds.feedLinesFor(feedDiagnostics, peer.nodeId)) log(`  ${line}`);
+      }
+    }
     return { code: checks.some((check) => !check.ok) ? 1 : 0 };
   }
   if (sub === 'identity') {
@@ -1151,7 +1167,32 @@ async function dispatchNodes(rest, flags, opts = {}) {
     }
     if (flags.visibility !== undefined) patch.visibility = flags.visibility;
     if (flags.selected !== undefined) patch.selected = String(flags.selected).split(',').map((x) => x.trim()).filter(Boolean);
-    return { code: nodesCmds.nodesEdit({ ...opts, log, ref, patch }).code };
+    // Federated access: a preset sets the whole vector, the granular flags
+    // refine one that was already set explicitly.
+    if (flags['access-role'] !== undefined) patch.accessRole = String(flags['access-role']);
+    for (const [flag, key] of [
+      ['events-access', 'eventsAccess'],
+      ['node-events-access', 'nodeEventsAccess'],
+      ['ask-reply-access', 'askReplyAccess'],
+      ['files-read-access', 'filesReadAccess'],
+      ['peer-operator-access', 'peerOperatorAccess'],
+    ]) {
+      if (flags[flag] === undefined) continue;
+      try { patch[key] = boolFlag(flags[flag], `--${flag}`); }
+      catch (e) { log(e.message); return { code: 1 }; }
+    }
+    // The client's OWN choice to import a peer's feed (never an owner grant):
+    // on|off, same shape as the other boolean switches.
+    if (flags['events-receive'] !== undefined) {
+      try { patch.eventsReceive = boolFlag(flags['events-receive'], '--events-receive'); }
+      catch (e) { log(e.message); return { code: 1 }; }
+    }
+    const expectedRevision = flags['access-revision'] === undefined ? undefined : Number(flags['access-revision']);
+    if (expectedRevision !== undefined && !Number.isInteger(expectedRevision)) {
+      log('nodes edit: --access-revision vuole un intero (la revision letta da `nodes access`)');
+      return { code: 1 };
+    }
+    return { code: nodesCmds.nodesEdit({ ...opts, log, ref, patch, expectedRevision }).code };
   }
   if (sub === 'rename') {
     if (flags.label === undefined) { log('nodes rename: --label TEXT obbligatorio'); return { code: 1 }; }
@@ -1202,6 +1243,12 @@ async function dispatchNodes(rest, flags, opts = {}) {
     }
     return { code: nodesCmds.nodesEdit({ ...opts, log, ref, patch: { liveHostAccess: arg === 'on' } }).code };
   }
+  // Inventario read-only delle concessioni: chi puo' fare cosa su QUESTO nodo,
+  // con la revisione della policy. E' il punto di partenza della migrazione
+  // esplicita: i peer non configurati restano negati finche' non lo sono.
+  if (sub === 'access') {
+    return { code: nodesCmds.nodesAccess({ ...opts, log, json: flags.json === true }).code };
+  }
   if (sub === 'remove') {
     if (flags.yes !== true) { log('nodes remove: conferma richiesta con --yes'); return { code: 1 }; }
     return { code: nodesCmds.nodesRemove({ ...opts, log, ref }).code };
@@ -1303,7 +1350,7 @@ function dispatch(argv, opts = {}) {
   const { flags, rest } = parseFlags(argv, CLI_VALUE_FLAGS);
   const cmd = rest[0];
 
-  // R29 — help come flag, deciso qui e solo qui: dopo parseFlags `--help`
+  // Help-as-flag handling come flag, deciso qui e solo qui: dopo parseFlags `--help`
   // finisce in flags e `-h` resta come posizionale dopo il sottocomando; in
   // entrambi i casi il sottocomando NON deve essere eseguito. Prima di questa
   // guardia `nexuscrew init --help` eseguiva init davvero: rigenerava i plist,

package/lib/cli/doctor.js

@@ -1,5 +1,5 @@
 'use strict';
-// nexuscrew doctor: auto-diagnosi (design §3, §7). [A2]
+// nexuscrew doctor: self-diagnosis entry point.
 // Struttura ESTENSIBILE: una lista di check-fn, ognuna ritorna
 //   { name, ok, warn?, detail? }. SSH è un requisito locale; la policy del
 // server remoto si prova soltanto tentando il forwarding reale.
@@ -276,7 +276,7 @@ function checkTmuxSurvival(platform, execImpl) {
   };
 }
 
-// ssh client presente su PATH: prerequisito dei tunnel multi-node (design §4).
+// ssh client on PATH: prerequisite for the multi-node tunnels.
 function checkSshClient(existsImpl) {
   return existsImpl('ssh')
     ? { name: 'OpenSSH transport', ok: true, detail: 'ssh presente · USATO dal supervisor NexusCrew' }
@@ -424,7 +424,7 @@ function checkTmuxServerCwd(platform, execImpl, opts = {}) {
 
 // Inspect only the single tmux global environment key required by
 // termux-exec. The value is validated and then discarded; it is never logged.
-// This distinguishes a healthy server from RC-2 (stale/no preload) and RC-7
+// This distinguishes a healthy server from a stale run (no preload) and one
 // (present but rejected by the trust boundary) without killing any session.
 function checkTmuxServerTermuxPreload(runtimeEnv, execImpl, opts = {}) {
   const env = runtimeEnv || process.env;
@@ -448,13 +448,13 @@ function checkTmuxServerTermuxPreload(runtimeEnv, execImpl, opts = {}) {
     };
 }
 
-// Check MCP identity (P0). NON-FAILING per costrutto: `ok` è sempre true, così
+// Check MCP identity. NON-FAILING per costrutto: `ok` è sempre true, così
 // chi usa NexusCrew solo come PWA (nessuna integrazione MCP) non vede mai il
 // doctor andare in FAIL solo per env MCP assente. Il check osserva SOLO la
 // presence delle env var di identità nel processo che lancia `doctor` (nessuna
 // lettura di ~/.codex/config.toml, cache private o config MCP).
 //
-// LIMITE DOCUMENTATO (P0): `doctor` non gira dentro il server MCP stdio e non può
+// LIMITE DOCUMENTATO: `doctor` non gira dentro il server MCP stdio e non può
 // distinguere in modo portatile "MCP configurato" da "PWA-only". Il WARN è quindi
 // conservativo e informativo: segnala l'assenza di identità osservabile a chi sta
 // configurando l'MCP, senza rompere l'utente PWA-only (per il quale ok resta true).

package/lib/cli/fleet-service.js

@@ -1,5 +1,5 @@
 'use strict';
-// B4.3 — Service companion (boot) generation + migration gate. Design §4c / §9b.
+// Service companion (boot) generation and migration gate.
 //
 // generateFleetService({platform, nodeBin, entryPath}) genera il contenuto del
 // service UNICO di boot (NON una unit per cella) che al boot esegue
@@ -44,7 +44,7 @@ function generateFleetService(opts) {
 function generateFleetLinux(opts) {
   const home = opts.home || os.homedir();
   const { nodeBin, entryPath } = opts;
-  // Parita' di hardening con service.js (M3): reject char non gestibili in systemd.
+  // Parita' di hardening con service.js: reject char non gestibili in systemd.
   assertSystemdSafe('home', home);
   assertSystemdSafe('nodeBin', nodeBin);
   assertSystemdSafe('entryPath', entryPath);
@@ -194,7 +194,7 @@ function selectProviderModeSync(cfg = {}) {
 
 // --- Install (speculare a installService di lib/cli/service.js) ---
 // Stesso hardening di service.js: no-symlink atomic (lstat + tmp+rename), failure
-// collection (NON ingoiare activation — M1), execImpl iniettabile (test). Differenze
+// Collection (NON ingoiare activation —), execImpl iniettabile (test). Differenze
 // companion:
 //  - nomi 'nexuscrew-fleet.*' + mode termux 0o755 (boot script eseguibile)
 //  - linux: daemon-reload + enable, NESSUN restart (Type=oneshot -> parte al boot)
@@ -209,7 +209,7 @@ function fleetInstallPath(platform, home) {
 }
 
 function fleetFileMode(platform) {
-  if (platform === 'termux') return 0o755; // boot script eseguibile (design §4c: chmod 755)
+  if (platform === 'termux') return 0o755; // boot script must stay executable (chmod 755)
   return 0o644;                            // systemd unit + launchd plist (come service.js)
 }
 
@@ -237,7 +237,7 @@ function fleetInstallCommands(platform, target, ctx) {
 
 // Install no-symlink + atomic rename (come service.js). execImpl iniettabile per test;
 // default execFileSync (argv diretto, MAI shell string). Su activation fallita il file
-// e' PRESERVATO e le failure raccolte per diagnosi (M1: non si ingoia, non si rollback).
+// E' PRESERVATO e le failure raccolte per diagnosi (it is never swallowed, non si rollback).
 // da revisione: `activate: false` (speculare a installService) scrive la definizione SENZA
 // toccare il service manager — per chi rigenera a meta' aggiornamento: il companion
 // e' RunAtLoad/oneshot, un bootstrap adesso eseguirebbe le celle boot:true mentre
@@ -255,7 +255,7 @@ function installFleetService(platform, content, ctx, {
   const target = ctx.installPath || fleetInstallPath(platform, home);
   const mode = fleetFileMode(platform);
 
-  // lstat: reject symlink preesistente (no-symlink atomic, parita' service.js [M3])
+  // Lstat: reject symlink preesistente (no-symlink atomic, parita' service.js)
   try {
     const st = fs.lstatSync(target);
     if (st.isSymbolicLink()) {
@@ -288,7 +288,7 @@ function installFleetService(platform, content, ctx, {
     return { target, mode, written: true, failures: [], skippedActivation: skipped };
   }
 
-  // exec service manager — raccogli failure per diagnosi (NON ingoiare, M1)
+  // Exec service manager — raccogli failure per diagnosi (NON ingoiare)
   const failures = [];
   if (platform === 'mac') {
     failures.push(...reinstallLaunchAgent(target, 'com.mmmbuto.nexuscrew-fleet', ctx, {

package/lib/cli/init.js

@@ -1,10 +1,10 @@
 'use strict';
-// nexuscrew init: orchestrazione setup portatile. [B2][M8][R4]
+// Nexuscrew init: orchestrazione setup portatile.
 // detectPlatform -> prereq (Node>=18 abort, tmux abort-before-service) ->
 // migration rule (porta da service esistente) -> config.json (preserva) ->
 // token (preserva) -> NexusFiles -> generateService -> installService (skip dry-run) ->
-// [B4.3] fleet companion (solo se provider builtin + gate ok; READONLY/dry-run skip;
-//   mai fa fallire l'init principale) -> print URL #token. Termux:boot best-effort.
+// fleet companion (only when the provider is builtin and the gate passes;
+//   never fails the main init) -> print URL #token. Termux boot: best-effort.
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
@@ -12,7 +12,7 @@ const crypto = require('node:crypto');
 const { detectPlatform, nodeBin, repoRoot, uid } = require('./platform.js');
 const { loadOrCreateToken } = require('../auth/token.js');
 const { generateService, installService, fileMode, installPath: svcInstallPath } = require('./service.js');
-// B4.3 — companion di boot del fleet (design §4c/§9b/§9d). Seam iniettabili per test.
+// Fleet boot companion. Injectable seams for tests.
 const {
   generateFleetService, installFleetService, migrationGate,
   selectProviderModeSync, fleetFileMode,
@@ -103,7 +103,7 @@ function ensureFleetDefaults(opts = {}) {
   return { path: fleetDefsPath, created: Boolean(creato), enabled: true };
 }
 
-// Migration rule (B2): se non c'è config.json, parse la porta dal service file esistente.
+// Migration rule: se non c'è config.json, parse la porta dal service file esistente.
 function readExistingPort(platform, home, installPathOverride) {
   const p = installPathOverride || svcInstallPath(platform, home);
   let raw;
@@ -139,7 +139,7 @@ function runInit(opts = {}) {
   const log = opts.log || (() => {});
   const tmuxOk = opts.tmuxOk !== undefined ? opts.tmuxOk : haveTmux(opts.tmuxBin || 'tmux', opts.env || process.env);
 
-  // prereq Node (abort before any write) [M8]
+  // Prereq Node (abort before any write)
   if (nodeMajor() < 18) {
     throw new Error(`Node >= 18 richiesto (attuale ${process.versions.node}). Aggiorna Node prima di init.`);
   }
@@ -161,7 +161,7 @@ function runInit(opts = {}) {
     if (migrated) { port = migrated; actions.push(`migration: porta ${port} letta dal service esistente`); }
   }
 
-  // config.json (scrivi se non esiste; preserva se esiste) [B2]
+  // Config.json (scrivi se non esiste; preserva se esiste)
   if (!dryRun) {
     fs.mkdirSync(configDir, { recursive: true });
     if (!fs.existsSync(configPath)) {
@@ -198,7 +198,7 @@ function runInit(opts = {}) {
   }
   if (!port) port = 41820;
 
-  // token (preserva esistente) [M4]
+  // Token (preserva esistente)
   let token;
   if (!dryRun) {
     token = loadOrCreateToken(tokenPath);
@@ -213,7 +213,7 @@ function runInit(opts = {}) {
     actions.push(`files root ${filesRoot}`);
   }
 
-  // nodes.json (B0): nodeId STABILE per installazione (generato qui se manca) +
+  // Nodes.json: nodeId STABILE per installazione (generato qui se manca) +
   // migrazione esplicita guarded dei nodes legacy da config.json. READONLY/dry-run
   // saltano; ogni errore -> WARN, MAI far fallire l'init.
   if (!dryRun && process.env.NEXUSCREW_READONLY !== '1' && !opts.readonly) {
@@ -244,7 +244,7 @@ function runInit(opts = {}) {
     port, home, uid: uid(),
     installPath: opts.installPath,
   };
-  // 1-bis (R23): la STESSA classe di difetto del companion di boot — nodeBin
+  // 1-bis: la STESSA classe di difetto del companion di boot — nodeBin
   // e entry finiscono versionati nell'unit/plist del servizio per-nodo. Si
   // risolve qui, alla scrittura, e si dichiara cio' che non ha alias stabile:
   // i due punti di scrittura non devono divergere (correggerne uno solo
@@ -262,7 +262,7 @@ function runInit(opts = {}) {
   } else if (dryRun) {
     actions.push(`DRY-RUN service (${platform}) generato, NON installato`);
   } else if (!tmuxOk) {
-    // tmux mancante: abort before service install (config/token gia' creati) [M8]
+    // Tmux mancante: abort before service install (config/token gia' creati)
     // Se il chiamante ha imposto tmuxOk direttamente (test/seam), non
     // abbiamo l'informazione per distinguere assenza da verifica bloccata:
     // il messaggio resta quello storico.
@@ -285,24 +285,24 @@ function runInit(opts = {}) {
         actions.push(skip);
       }
       if (r.failures && r.failures.length) {
-        // file installato MA activation (systemctl/launchctl) fallita [M1]
+        // File installato MA activation (systemctl/launchctl) fallita
         installFailures.push({ component: 'service', phase: 'activation' });
         actions.push(`WARN: service file installato ${r.target} MA activation fallita: ${r.failures.map((f) => f.cmd).join('; ')} (file preservato, diagnosi)`);
       } else {
         actions.push(`service installed ${r.target} (mode 0${fileMode(platform).toString(8)})`);
       }
     } catch (e) {
-      // failure: preserve file + diagnosi (no rollback) [M8]
+      // Failure: preserve file + diagnosi (no rollback)
       installFailures.push({ component: 'service', phase: 'install' });
       actions.push(`WARN: service install fallito: ${e.message} (file generati preservati)`);
     }
   }
 
-  // --- B4.3 companion: service di boot del fleet (design §4c/§9b/§9d) ---
-  // Il companion si installa SOLO se il provider e' builtin (§9b) e il migration
-  // gate non rileva unit legacy cloud-cell@*.service abilitate (no doppio boot).
-  // READONLY blocca ogni azione del companion (§9d). MAI far fallire l'init
-  // principale: ogni errore del companion -> WARN action + return normale.
+  // --- Fleet boot companion service ---
+  // The companion installs ONLY when the provider is builtin and the migration
+  // gate finds no enabled legacy cloud-cell@*.service units (no double boot).
+  // READONLY blocks every companion action. Never let it fail the main init:
+  //   any companion error -> WARN action + normal return.
   try {
     const readonly = process.env.NEXUSCREW_READONLY === '1' || opts.readonly;
     if (!installBoot) {
@@ -310,9 +310,9 @@ function runInit(opts = {}) {
     } else if (readonly) {
       actions.push('fleet companion: READONLY, non installato');
     } else {
-      // provider mode: companion SOLO se builtin (§9b). selectProviderModeSync e'
-      // il default SINCRONO (runInit e' sync: bin chiama process.exit dopo dispatch,
-      // selectProvider async non sopravvive). Seam opts.selectProvider per i test.
+      // provider mode: companion ONLY when builtin. selectProviderModeSync is
+      // the synchronous default (runInit is sync: the bin calls process.exit after
+      // dispatch, an async selectProvider would not survive). Seam opts.selectProvider for tests.
       const selectProvider = opts.selectProvider || selectProviderModeSync;
       const fleetCfg = opts.fleetCfg || {
         home,
@@ -324,16 +324,16 @@ function runInit(opts = {}) {
       if (sel.mode !== 'builtin') {
         actions.push(`fleet companion: non installato (provider ${sel.mode})`);
       } else {
-        // migration gate (§9b): seam opts.migrationGate iniettabile; default quello
-        // di fleet-service.js (exec iniettabile via opts.execImpl). blocked -> NON
-        // installare (mai doppio boot silenzioso).
+        // migration gate: seam opts.migrationGate injectable; the fleet-service.js
+        // one (injectable exec via opts.execImpl). Blocked -> do NOT
+        // install (never a silent double boot).
         const gate = (opts.migrationGate || migrationGate)({ exec: opts.execImpl, platform });
         if (gate.blocked) {
           actions.push(`WARN: fleet companion NON installato — migration gate bloccato: ${(gate.units || []).join(', ')} (${gate.remediation || 'disabilita le unit legacy cloud-cell@*.service'})`);
         } else if (dryRun) {
           actions.push('DRY-RUN fleet companion generato, NON installato');
         } else {
-          // R23: i path del boot si risolvono alla SCRITTURA del servizio (mai
+          // I path del boot si risolvono alla SCRITTURA del servizio (mai
           // a ogni avvio): un alias stabile che risolva allo stesso file, se
           // c'e'; altrimenti il path attuale, DICHIARATO — un avviso adesso e'
           // meglio di un path che scade in silenzio (vedi stable-alias.js).
@@ -355,7 +355,7 @@ function runInit(opts = {}) {
           if (fr.skippedActivation) {
             actions.push(`fleet companion ${fr.target}: activation skipped (--no-activate)`);
           } else if (fr.failures && fr.failures.length) {
-            // file installato MA activation (systemctl/launchctl) fallita [M1]
+            // File installato MA activation (systemctl/launchctl) fallita
             installFailures.push({ component: 'fleet-companion', phase: 'activation' });
             actions.push(`WARN: fleet companion file installato ${fr.target} MA activation fallita: ${fr.failures.map((f) => f.cmd).join('; ')} (file preservato, diagnosi)`);
           } else {
@@ -370,7 +370,7 @@ function runInit(opts = {}) {
     actions.push(`WARN: fleet companion fallito: ${e.message} (init principale prosegue)`);
   }
 
-  // Termux:boot best-effort detection (R4)
+  // Termux:boot best-effort detection
   if (platform === 'termux' && installBoot) {
     const bootDir = path.join(home, '.termux', 'boot');
     const bootOk = fs.existsSync(bootDir);

package/lib/cli/pidfile.js

@@ -2,7 +2,7 @@
 // Pidfile con verified kill: metadata {pid, cmd, startTs}; kill verifica cmd+pid
 // prima di signalare (no broad match by name). Il controllo pid+nascita riduce
 // il PID reuse a una finestra residua fra verifica e segnale — non lo elimina;
-// dettaglio e motivo nel commento sopra il kill in killPidfile. [R1]
+// Dettaglio e motivo nel commento sopra il kill in killPidfile.
 // Primario su Termux (serve --pidfile); opzionale --manual su linux/mac.
 const fs = require('node:fs');
 const os = require('node:os');

package/lib/cli/service.js

@@ -1,6 +1,6 @@
 'use strict';
 // Service generation per-platform: systemd --user (linux), launchd plist (mac),
-// Termux:boot script. Escaping per-platform + install no-symlink atomic. [M2][M3][B1][R2][R3]
+// Termux:boot script. Escaping per-platform + install no-symlink atomic.
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
@@ -42,7 +42,7 @@ function shellQuote(s) {
 }
 
 // systemd ExecStart non gestisce bene alcuni char (", $, ;, backtick, newline, apice)
-// nemmeno con escaping ad hoc: reject esplicito con errore chiaro. [M3]
+// Nemmeno con escaping ad hoc: reject esplicito con errore chiaro.
 // space e % sono ok (escaped). Path repo normali non hanno questi char.
 const SYSTEMD_FORBIDDEN = /[";$`\n']/;
 function assertSystemdSafe(label, p) {
@@ -54,7 +54,7 @@ function assertSystemdSafe(label, p) {
 // --- Templates ---
 
 // Entry del servizio: di norma derivato da repoRoot; i punti di scrittura
-// che risolvono l'alias stabile (R23/1-bis, stable-alias.js) passano
+// Che risolvono l'alias stabile (/1-bis, stable-alias.js) passano
 // l'entryPath gia' risolto. Contratto vecchio intatto: senza entryPath si
 // deriva da repoRoot come prima.
 function serviceEntryPath(ctx) {
@@ -69,7 +69,7 @@ function generateService(platform, ctx) {
 }
 
 function generateLinux(ctx) {
-  assertSystemdSafe('repoRoot', ctx.repoRoot); // [M3] reject char non gestibili
+  assertSystemdSafe('repoRoot', ctx.repoRoot); // Reject char non gestibili
   assertSystemdSafe('nodeBin', ctx.nodeBin);
   // HOME is stable across init/repair/update. The runtime directory may be
   // atomically replaced; keeping it as the service cwd leaves the HTTP process
@@ -304,7 +304,7 @@ function reinstallLaunchAgent(target, serviceName, ctx, opts = {}) {
   }
 }
 
-// Install no-symlink + atomic rename. [M3]
+// Install no-symlink + atomic rename.
 // - lstat target: reject symlink (no follow)
 // - write temp file nella stessa dir -> chmod mode -> atomic rename
 // - exec service manager (systemctl/launchctl); skip in dryRun
@@ -352,7 +352,7 @@ function installService(platform, content, ctx, {
     throw e;
   }
 
-  // exec service manager — NON ingoiare failure (M1): raccogli per diagnosi
+  // Exec service manager — NON ingoiare failure: raccogli per diagnosi
   const cmds = installCommands(platform, target, ctx);
   const activation = planActivation(platform, target, ctx, { execImpl, activate });
   if (!activation.activate) {

package/lib/cli/stable-alias.js

@@ -1,5 +1,5 @@
 'use strict';
-// R23 — alias stabili per i path del servizio di boot.
+// Alias stabili per i path del servizio di boot.
 //
 // Il companion di boot scrive nodeBin e entryPath LETTERALMENTE nel plist
 // launchd (ProgramArguments[0]) e nell'unit systemd (ExecStart=). Quei path
@@ -17,7 +17,7 @@
 // Se c'e', scrivere quello; se no, scrivere il path attuale e DICHIARARLO:
 // un avviso alla scrittura e' meglio di un path che scade in silenzio.
 //
-// Tre vincoli non negoziabili (briefing R23):
+// Tre vincoli non negoziabili (briefing):
 // 1. La verifica «e' lo stesso file» si fa alla SCRITTURA del servizio, MAI a
 //    ogni avvio: dopo l'upgrade il symlink DEVE puntare a un node diverso —
 //    e' l'effetto voluto. Un controllo di identita' permanente si
@@ -116,7 +116,7 @@ function resolveBootPaths({ nodeBin, entryPath, env = process.env, realpath } =
 // morto: il suo criterio e' «alias che realpath allo STESSO file», e un file
 // morto non e' lo stesso file di nessuno. Il criterio qui e' diverso e
 // dichiarato: un path VIVO — l'alias stabile dello stesso file quando
-// l'attuale vive (R23 intatto), altrimenti il primo candidato stabile che
+// L'attuale vive (intatto), altrimenti il primo candidato stabile che
 // ESISTE, con la dichiarazione; se non c'e' niente di vivo, il path resta e
 // la dichiarazione dice di rilanciare init. `env`, `realpath` e `exists`
 // iniettabili per test.
@@ -127,7 +127,7 @@ function resolveLiveBootPaths({ nodeBin, entryPath, env = process.env, realpath,
   const revive = (current, candidates, what) => {
     try {
       realpathImpl(current);
-      return null; // vivo: decide il criterio R23 di resolveBootPaths
+      return null; // Vivo: decide il criterio di resolveBootPaths
     } catch (_) { /* morto su disco: cerca una alternativa viva */ }
     for (const candidate of Array.isArray(candidates) ? candidates : []) {
       if (existsImpl(candidate)) {

package/lib/cli/url.js

@@ -1,5 +1,5 @@
 'use strict';
-// URL/token helpers per la CLI unificata (design §3). [A2]
+// URL/token helpers for the unified CLI.
 // - resolvePaths: config/token path home-aware (seam per test con HOME temporanea).
 // - readToken: legge il token esistente SENZA crearlo (no-follow symlink), null se assente.
 // - loadPort: porta corrente (opts > env > config.json > default 41820).

package/lib/config.js

@@ -17,7 +17,7 @@ function baseDefaults() {
   return {
     bind: '127.0.0.1',
     port: 41820,
-    // Seconda porta loopback, SOLO per /panel/* (P0 sicurezza 2026-08-16):
+    // Seconda porta loopback, SOLO per /panel/* (sicurezza 2026-08-16):
     // un pannello vive su un'origin diversa dal control plane — la porta fa
     // parte dell'origin, quindi un iframe cross-porta non legge il
     // localStorage del padre, qualunque JS esegua il container. Nessuna API
@@ -57,14 +57,14 @@ function baseDefaults() {
     // Il manager aggiorna solo verso una semver superiore: mai downgrade.
     autoUpdate: true,
     sessionPresets: {},
-    // Ponte Live (fetta 3, rev5 MC0): isolabile — a false il ponte non si
+    // Ponte Live (fetta 3, rev5): isolabile — a false il ponte non si
     // connette mai e ogni avvio di Live resta sul comportamento standard.
     liveBridgeEnabled: true,
     // Socket di controllo dell'app-server (misurato 2026-08-15:
     // $CODEX_HOME/app-server-control/app-server-control.sock, WebSocket sopra
     // unix socket). Non cablare mai una porta al posto di questo path.
     liveBridgeSocketPath: path.join(os.homedir(), '.codex', 'app-server-control', 'app-server-control.sock'),
-    // MC1.5: limite dichiarato per OGNI fase del ponte (GET designazione e
+    // Limite dichiarato per OGNI fase del ponte (GET designazione e
     // sessione sul socket). Oltre questo la Live parte senza puntamento.
     liveBridgeTimeoutMs: 1500,
     // PTY grace is finite and configurable for mobile handovers. The caps keep
@@ -82,7 +82,37 @@ function configJsonPath() {
   return process.env.NEXUSCREW_CONFIG_FILE || path.join(os.homedir(), '.nexuscrew', 'config.json');
 }
 
-// Legge ~/.nexuscrew/config.json se esiste (nuovo, B2). {} se assente/malformato.
+// Legge ~/.nexuscrew/config.json se esiste (nuovo). {} se assente/malformato.
+// federation.events.enabled — the node-level kill switch for the event feed.
+// STRICT boolean: only the literal false disables. A truthy string or any
+// other type never enables anything beyond the default, and never disables by
+// accident: "false" (string) is not a decision, it is noise, and the default
+// holds. Without explicit grants nothing is enabled either way — the switch
+// only stops what grants already allow.
+function eventsEnabledFlag(raw, log = console.warn) {
+  // Fail-closed strictness: only the literal true/false is a decision. A
+  // missing value keeps the default (enabled); ANY other type — "false" as a
+  // string, 0, null, an object — is invalid config, is treated as DISABLED and
+  // is reported: silently enabling on garbage is how switches lie.
+  if (raw === undefined) return true;
+  if (raw === true) return true;
+  if (raw === false) return false;
+  try { log('config: federation.events.enabled must be a boolean; invalid value treated as disabled'); } catch (_) {}
+  return false;
+}
+
+function readFederationEventsEnabled(opts = {}) {
+  if (typeof opts.federationEventsEnabled === 'boolean') return opts.federationEventsEnabled;
+  let cfg = {};
+  try {
+    const raw = fs.readFileSync(opts.configJsonPath || configJsonPath(), 'utf8');
+    cfg = JSON.parse(raw) || {};
+  } catch (_) { cfg = {}; }
+  const fed = cfg && typeof cfg.federation === 'object' && cfg.federation ? cfg.federation : null;
+  const events = fed && typeof fed.events === 'object' && fed.events ? fed.events : null;
+  return eventsEnabledFlag(events ? events.enabled : undefined);
+}
+
 function readConfigJson() {
   try {
     const raw = fs.readFileSync(configJsonPath(), 'utf8');
@@ -134,7 +164,7 @@ function envOverrides() {
   return e;
 }
 
-// Precedence: baseDefaults < config.json < env < opts. [B2]
+// Precedence: baseDefaults < config.json < env < opts.
 // Le credenziali authority vivono in due file 0600 nella dir
 // dell'authority (default ~/.nexuscrew/identity-authority). Se esistono vengono
 // caricate qui, senza MAI loggare i valori: builtin costruisce l'authority
@@ -195,4 +225,4 @@ function defaults() {
   return { ...baseDefaults(), ...envOverrides() };
 }
 
-module.exports = { assertLoopback, baseDefaults, readConfigJson, loadConfig, defaults, LOOPBACK, configJsonPath };
+module.exports = { assertLoopback, baseDefaults, readConfigJson, loadConfig, defaults, LOOPBACK, configJsonPath, eventsEnabledFlag, readFederationEventsEnabled };

package/lib/files/routes.js

@@ -55,7 +55,7 @@ function filesRoutes({
       // paste=false (tasto allegati del composer): il client appende il path al
       // testo del composer — niente scrittura PTY. Default = incolla (FilesPanel).
       const wantPaste = String((req.body && req.body.paste) || '') !== 'false';
-      // R31-A2: paste RICHIESTO ma non riuscito non e' un 200 con pasted:false —
+      // : paste RICHIESTO ma non riuscito non e' un 200 con pasted:false —
       // tre cause collassavano in quell'unica etichetta muta (non richiesto /
       // tmux non ha ricevuto / testo respinto) e nessuno, risposta o UI, poteva
       // accorgersene. Il vocabolario e' quello del ramo answer degli ask

package/lib/fleet/boot.js

@@ -1,9 +1,9 @@
 'use strict';
-// B4.3 — Service companion boot. bootCells(fleet, {log}) avvia tutte le celle
+// Fleet boot companion: bootCells(fleet, {log}) starts the boot:true cells
 // boot:true di un fleet provider (builtin) chiamandone up(). Una cella gia' in
 // esecuzione (up -> httpError 409 / "duplicate session") = SKIP non fatale;
 // ogni altro errore viene raccolto in failed[] e NON ferma le altre celle.
-// Nessun side-effect all'import. Design §4c / §9b.
+// No side effects on import.
 //
 // Agnostico: usa solo il contratto fleet {available, status(), up()} — non legge
 // internals delle definizioni. La lista delle celle boot:true arriva da status()