@mmmbuto/nexuscrew 0.9.28 → 0.9.30

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;
@@ -131,11 +131,15 @@ function runInit(opts = {}) {
   const tokenPath = opts.tokenPath || path.join(configDir, 'token');
   const filesRoot = opts.filesRoot || path.join(home, 'NexusFiles');
   const dryRun = !!opts.dryRun;
+  // Write the boot definitions without asking the service manager to load them.
+  // Needed by smoke runs and temporary prefixes, where the per-UID manager would
+  // otherwise act on the real installation (see planActivation in service.js).
+  const noActivate = !!opts.noActivate || opts.activate === false;
   const installBoot = opts.installBoot !== false;
   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.`);
   }
@@ -144,6 +148,11 @@ function runInit(opts = {}) {
   // Structured, value-free install outcomes for callers that must fail closed
   // (notably smart-up migrations). Human-readable actions remain compatible.
   const installFailures = [];
+  // Outcome of the boot-definition activation: 'activated', 'skipped-by-flag'
+  // (--no-activate) or 'skipped-foreign-manager' (the manager loads another
+  // definition). Declared to callers that must not confuse a deliberate skip
+  // with a fresh activation.
+  let serviceActivation = null;
 
   // porta: opts.port > migration rule > config esistente > default 41820
   let port = opts.port;
@@ -152,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)) {
@@ -189,7 +198,7 @@ function runInit(opts = {}) {
   }
   if (!port) port = 41820;
 
-  // token (preserva esistente) [M4]
+  // Token (preserva esistente)
   let token;
   if (!dryRun) {
     token = loadOrCreateToken(tokenPath);
@@ -204,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) {
@@ -235,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
@@ -253,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.
@@ -264,26 +273,36 @@ function runInit(opts = {}) {
   } else {
     for (const w of svcBoot.warnings) actions.push(`WARN service: ${w}`);
     try {
-      const r = installService(platform, content, svcCtx, { execImpl: opts.execImpl });
+      const r = installService(platform, content, svcCtx, {
+        execImpl: opts.execImpl,
+        activate: !noActivate,
+      });
+      serviceActivation = r.activation || null;
+      if (r.activation && r.activation.warning) {
+        const skip = r.activation.outcome === 'skipped-by-flag'
+          ? r.activation.warning
+          : `WARN: ${r.activation.warning}`;
+        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) {
@@ -291,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,
@@ -305,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).
@@ -331,10 +350,12 @@ function runInit(opts = {}) {
           const fr = installFleetService(
             platform, fleetContent,
             { home, uid: uid(), installPath: opts.fleetInstallPath },
-            { execImpl: opts.execImpl },
+            { execImpl: opts.execImpl, activate: !noActivate },
           );
-          if (fr.failures && fr.failures.length) {
-            // file installato MA activation (systemctl/launchctl) fallita [M1]
+          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
             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 {
@@ -349,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);
@@ -367,7 +388,10 @@ function runInit(opts = {}) {
 
   for (const a of actions) log(a);
 
-  return { platform, port, token, url: urlWithToken, actions, installFailures, tmuxOk, dryRun };
+  return {
+    platform, port, token, url: urlWithToken, actions, installFailures,
+    serviceActivation, tmuxOk, dryRun,
+  };
 }
 
 module.exports = { runInit, readExistingPort, haveTmux, nodeMajor, writeConfigAtomic, ensureFleetDefaults };

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,15 +352,20 @@ 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);
-  if (!activate) {
+  const activation = planActivation(platform, target, ctx, { execImpl, activate });
+  if (!activation.activate) {
+    // The manager will not run what this HOME just wrote, or the caller asked to
+    // write without activating: the skipped plan stays declared, and a skip for a
+    // foreign HOME says why instead of touching a service that is not ours.
     return {
       target,
       mode,
       written: true,
       failures: [],
       skippedActivation: cmds.map(([bin, args]) => `${bin} ${args.join(' ')}`),
+      activation,
     };
   }
   const failures = [];
@@ -380,7 +385,7 @@ function installService(platform, content, ctx, {
     }
   }
 
-  return { target, mode, written: true, failures };
+  return { target, mode, written: true, failures, activation };
 }
 
 function installCommands(platform, target, ctx) {
@@ -407,6 +412,116 @@ function installCommands(platform, target, ctx) {
 }
 
 
+// --- Activation guard -------------------------------------------------------
+// The user service manager is per-UID, not per-HOME. `systemctl --user` and
+// `launchctl` resolve our unit by NAME inside the namespace of the logged-in
+// user, while this module writes the definition under the HOME it was given.
+// A run with a temporary HOME therefore wrote a definition the manager never
+// loads, and the activation commands still hit the real manager: the REAL
+// service was restarted twice during a single smoke run on the live node.
+//
+// Decide ONCE, before the activation commands, reading back WHICH definition the
+// manager has loaded. If it is not the one just written, activation is skipped
+// and said out loud, instead of touching a service this HOME does not own.
+const ACTIVATION_OUTCOMES = Object.freeze({
+  activated: 'activated',
+  skippedByFlag: 'skipped-by-flag',
+  skippedForeignManager: 'skipped-foreign-manager',
+  notApplicable: 'not-applicable',
+});
+
+const NO_ACTIVATE_WARNING = (target) =>
+  `unit installed at ${target}, activation skipped: no service manager command was run`;
+
+function foreignManagerWarning(target, managerPath) {
+  return `unit installed at ${target} but the user service manager loads ${managerPath}: `
+    + 'activation skipped, run `nexuscrew restart` from that home or use --no-activate';
+}
+
+// Two paths name the same file when they resolve to the same inode path; the
+// manager reports its own canonical form, so compare canonically on both sides.
+function sameDefinitionPath(a, b) {
+  const canonical = (p) => {
+    try { return fs.realpathSync(p); } catch (_) { return path.resolve(String(p)); }
+  };
+  return canonical(a) === canonical(b);
+}
+
+// Which definition does the user service manager have loaded for our unit?
+//   absent   nothing loaded, or no readable answer: activation stays as it was
+//   same     it loads the definition just written
+//   foreign  it loads a DIFFERENT definition: this HOME does not own that service
+//
+// The guard fires on POSITIVE evidence only. An answer we cannot read as a
+// definition path is never turned into a silent behaviour change: it keeps the
+// previous activation path instead of guessing.
+function readLoadedDefinition(platform, target, ctx, execImpl) {
+  if (platform === 'linux') {
+    let raw;
+    try {
+      raw = execImpl('systemctl', [
+        '--user', 'show', 'nexuscrew.service', '--property=FragmentPath', '--value',
+      ], { encoding: 'utf8' });
+    } catch (_) {
+      // No probing possible (no user manager): the activation commands below fail
+      // the same way and are reported as failures, exactly as they were before.
+      return { state: 'absent', path: null };
+    }
+    const loaded = typeof raw === 'string' ? raw.trim() : '';
+    if (!loaded) return { state: 'absent', path: null };
+    return sameDefinitionPath(loaded, target)
+      ? { state: 'same', path: loaded }
+      : { state: 'foreign', path: loaded };
+  }
+  if (platform === 'mac') {
+    const label = `gui/${ctx.uid || uid()}/com.mmmbuto.nexuscrew`;
+    let raw;
+    try {
+      raw = execImpl('launchctl', ['print', label], { encoding: 'utf8' });
+    } catch (_) {
+      return { state: 'absent', path: null }; // not loaded
+    }
+    const match = typeof raw === 'string' ? raw.match(/^\s*path = (.+?)\s*$/m) : null;
+    if (!match) return { state: 'absent', path: null };
+    return sameDefinitionPath(match[1], target)
+      ? { state: 'same', path: match[1] }
+      : { state: 'foreign', path: match[1] };
+  }
+  return { state: 'absent', path: null };
+}
+
+// The single decision point for activation: callers write the definition, then
+// ask this whether the manager may be touched at all.
+function planActivation(platform, target, ctx, { execImpl = execFileSync, activate = true } = {}) {
+  if (platform === 'termux') {
+    return { activate: false, outcome: ACTIVATION_OUTCOMES.notApplicable, managerPath: null, warning: null };
+  }
+  if (!activate) {
+    return {
+      activate: false,
+      outcome: ACTIVATION_OUTCOMES.skippedByFlag,
+      managerPath: null,
+      warning: NO_ACTIVATE_WARNING(target),
+    };
+  }
+  const loaded = readLoadedDefinition(platform, target, ctx, execImpl);
+  if (loaded.state === 'foreign') {
+    return {
+      activate: false,
+      outcome: ACTIVATION_OUTCOMES.skippedForeignManager,
+      managerPath: loaded.path,
+      warning: foreignManagerWarning(target, loaded.path),
+    };
+  }
+  return {
+    activate: true,
+    outcome: ACTIVATION_OUTCOMES.activated,
+    managerPath: loaded.path,
+    warning: null,
+  };
+}
+
+
 // --- Riconoscimento di PROPRIETA' (da revisione) -------------------------
 // La sanazione automatica riscrive una definizione solo se e' NOSTRA. La prima
 // versione cercava /nexuscrew/i nel contenuto: un unit di terzi che ci nomina
@@ -456,6 +571,7 @@ module.exports = {
   isOurService, OUR_SERVICE_ANCHOR,
   generateService, generateLinux, generateMac, generateTermux,
   installService, installPath, installCommands, fileMode,
+  planActivation, readLoadedDefinition, sameDefinitionPath, ACTIVATION_OUTCOMES,
   ensureLinuxTmuxSurvival, linuxTmuxSurvivalPath, LINUX_TMUX_SURVIVAL_DROPIN,
   reinstallLaunchAgent, waitForLaunchdUnload,
   escapeSystemdPath, escapeSystemdExec, escapeXml, shellQuote,

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()