@mmmbuto/nexuscrew 0.8.39 → 0.8.41

package/lib/proxy/hop-proof.js

@@ -0,0 +1,50 @@
+'use strict';
+// lib/proxy/hop-proof.js — prova che una richiesta arrivata su /api e' l'ULTIMO
+// hop di una route federata generata da QUESTO processo, non un POST diretto di
+// un client locale che ha semplicemente scritto gli header a mano.
+//
+// Perche' serve. `controlledVisited()` lega gia' `x-nexuscrew-visited` al peer
+// autenticato dal suo acceptToken, ma l'ultimo hop entra in `/api/<resource>`
+// con il Bearer LOCALE: a quel punto l'handler non distingue piu' un inbound
+// federato da una richiesta diretta di chiunque possieda il token della UI.
+// `cleanHeaders()` cancella gia' `x-nexuscrew-{route,visited,hop}` da ogni
+// header in ingresso, quindi il canale e' riservato: basta renderlo non
+// riproducibile. La firma usa un segreto casuale per-processo, mai su disco,
+// mai esposto da un'API: un client locale non puo' calcolarla.
+//
+// Il payload firmato include metodo e path oltre alla catena visited, cosi' una
+// prova non e' trasportabile su un'altra risorsa o su un altro verbo.
+const crypto = require('node:crypto');
+
+const HOP_HEADER = 'x-nexuscrew-hop';
+const PREFIX = 'NEXUSCREW-HOP-V1';
+
+function createHopSecret() {
+  return crypto.randomBytes(32);
+}
+
+function canonicalHop({ method, path: reqPath, visited }) {
+  const chain = Array.isArray(visited) ? visited.join(',') : String(visited || '');
+  return `${PREFIX}\n${String(method || '').toUpperCase()}\n${String(reqPath || '')}\n${chain}`;
+}
+
+// signHop(): hex HMAC-SHA256. Ritorna null senza segreto, cosi' un server che
+// non ha inizializzato la prova non emette un header vuoto interpretabile.
+function signHop(secret, parts) {
+  if (!secret) return null;
+  return crypto.createHmac('sha256', secret).update(canonicalHop(parts)).digest('hex');
+}
+
+// verifyHop(): confronto timing-safe. Fail-closed su qualunque anomalia
+// (segreto assente, header assente, lunghezza diversa, hex non valido).
+function verifyHop(secret, parts, proof) {
+  if (!secret || typeof proof !== 'string' || !/^[a-f0-9]{64}$/i.test(proof)) return false;
+  const expected = signHop(secret, parts);
+  if (!expected) return false;
+  const a = Buffer.from(expected, 'hex');
+  const b = Buffer.from(proof.toLowerCase(), 'hex');
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+module.exports = { createHopSecret, signHop, verifyHop, canonicalHop, HOP_HEADER };

package/lib/server.js

@@ -32,6 +32,17 @@ const nodesInventory = require('./nodes/inventory.js');
 const topologyCache = require('./nodes/topology-cache.js');
 const { createNodeProxy, handleNodeUpgrade } = require('./proxy/node-proxy.js');
 const federation = require('./proxy/federation.js');
+const { audioRoutes } = require('./audio/routes.js');
+const { isConsent: isAudioConsent } = require('./audio/consent.js');
+const { createOriginResolver } = require('./audio/origin.js');
+const { createAudioAcl } = require('./audio/acl.js');
+const { createDispatcher } = require('./audio/dispatch.js');
+const { createSpeakQueue } = require('./audio/queue.js');
+const { createReceiptStore } = require('./audio/receipt.js');
+const audioAdapters = require('./audio/adapters.js');
+const audioGroups = require('./audio/groups.js');
+const { bridgeSecretPath, loadOrCreateBridgeSecret, createNonceCache } = require('./audio/bridge-auth.js');
+const { createHopSecret } = require('./proxy/hop-proof.js');
 const { settingsRoutes, publicPeeringRoutes } = require('./settings/routes.js');
 const decksStore = require('./decks/store.js');
 const { decksRoutes } = require('./decks/routes.js');
@@ -133,6 +144,22 @@ function createServer(opts = {}) {
   const topologyCachePath = cfg.topologyCachePath || topologyCache.defaultPath(cfg.home || os.homedir());
   const decksPath = cfg.decksPath || decksStore.defaultDecksPath(cfg.home || os.homedir());
   const proxyReadonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
+  const audioHome = cfg.home || os.homedir();
+  // Stato audio ancorato alla directory del token (come notifyDir): server,
+  // Settings e bridge MCP devono guardare gli stessi file anche quando un test
+  // isola l'istanza fuori dalla home reale.
+  const audioCfg = {
+    home: audioHome,
+    tokenPath: cfg.tokenPath,
+    audioConsentPath: cfg.audioConsentPath,
+    audioGroupsPath: cfg.audioGroupsPath,
+    audioBridgeSecretPath: cfg.audioBridgeSecretPath || path.join(notifyDir, 'audio-bridge.key'),
+  };
+  // Segreto per-processo della prova di hop federata: vive solo in memoria, non
+  // e' su disco e nessuna API lo espone. Serve a distinguere l'ultimo hop di una
+  // route federata da un POST diretto di chi possiede il token della UI.
+  const hopSecret = createHopSecret();
+  const audioNonceCache = createNonceCache();
   function resolveNode(name) {
     const st = nodesStore.loadStore(nodesPath);
     if (!st) return null;
@@ -246,7 +273,10 @@ function createServer(opts = {}) {
     try {
       const { name, cwd, preset } = req.body || {};
       await createSession(cfg.tmuxBin, { name, cwd, preset },
-        { home: os.homedir(), presets: cfg.sessionPresets, ensureProtection: ensureTmuxProtection });
+        {
+          home: os.homedir(), presets: cfg.sessionPresets, ensureProtection: ensureTmuxProtection,
+          alternateScreen: cfg.alternateScreen, log: cfg.log,
+        });
       res.status(201).json({ created: true, name });
     } catch (e) { res.status(e.status || 500).json({ error: String(e.message || e) }); }
   });
@@ -299,6 +329,64 @@ function createServer(opts = {}) {
     sessionExists: (name) => sessionExists(cfg.tmuxBin, name),
   }));
   api.use('/fleet', fleetRoutes(fleetP, { ...cfg, diagnostics }));
+  // Audio Share. L'identita' del nodo NON e' un campo di cfg: si legge dal node
+  // store, la stessa fonte usata da /api/cells e /api/peers. Lo stato Fleet e'
+  // asincrono e va atteso: leggerlo come se fosse sincrono lascerebbe la
+  // risoluzione dell'origine sempre vuota e la feature morta senza che un test
+  // sul router se ne accorga.
+  const audioNodeId = () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
+  // Seam di test per l'adapter: permette di esercitare il percorso completo
+  // (route -> gate -> coda -> receipt) sul server REALE senza emettere suono.
+  // In produzione resta il probe locale.
+  const audioAdapter = cfg.audioAdapterSeam
+    || audioAdapters.createAdapter(audioAdapters.detectAdapter({ env: cfg.env || process.env }));
+  const audioReceipts = createReceiptStore();
+  const audioQueue = createSpeakQueue({
+    adapter: audioAdapter,
+    // La coda e' l'unica a sapere com'e' finito davvero un enunciato: e' lei ad
+    // aggiornare il receipt da `accepted` a spoken/refused/unknown.
+    onStatus: (utteranceId, status, reason) => { try { audioReceipts.update(utteranceId, status, reason); } catch (_) {} },
+  });
+  api.use('/audio', audioRoutes({
+    readonly: proxyReadonly,
+    localNodeId: audioNodeId,
+    receiptStore: audioReceipts,
+    adapter: audioAdapter,
+    queue: audioQueue,
+    acl: createAudioAcl({ nodesPath }),
+    consent: () => { try { return isAudioConsent(audioCfg, audioHome); } catch (_) { return false; } },
+    originResolver: createOriginResolver({
+      localNodeId: audioNodeId,
+      // Celle Fleet ATTIVE in questo momento, attese davvero.
+      activeCells: async () => {
+        const fleet = await fleetP;
+        if (!fleet || fleet.available !== true || typeof fleet.status !== 'function') return [];
+        const st = await fleet.status();
+        return Array.isArray(st && st.cells) ? st.cells.map((c) => ({
+          cell: c && c.cell, tmuxSession: c && c.tmuxSession,
+          active: c && c.active === true && c.tmux !== false,
+        })) : [];
+      },
+      bridgeSecret: () => { try { return loadOrCreateBridgeSecret(bridgeSecretPath(audioCfg, audioHome)); } catch (_) { return null; } },
+      hopSecret: () => hopSecret,
+      nonceCache: audioNonceCache,
+    }),
+    dispatcher: createDispatcher({
+      localNodeId: audioNodeId,
+      peers: async () => {
+        const st = nodesStore.loadStore(nodesPath);
+        if (!st) return [];
+        const topology = await federation.collectLocalTopology({ nodesPath, cachePath: topologyCachePath, fetchImpl: healthFetch });
+        return nodesInventory.buildInventory({
+          direct: nodesStore.redactStore(st).nodes,
+          topology: topology && Array.isArray(topology.nodes) ? topology.nodes : [],
+        });
+      },
+      localPort: () => (server && server.address() ? server.address().port : cfg.port),
+      localToken: () => tokenHolder.value,
+    }),
+    getGroup: (name) => audioGroups.getGroup(audioCfg, name, audioHome),
+  }));
   api.use('/cells', cellsRoutes({
     fleetP,
     instanceId: () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null,
@@ -359,7 +447,12 @@ function createServer(opts = {}) {
   // Settings API B2 (design §4b(6)): read-only GET + mutanti lista chiusa per il
   // wizard/settings UI. Dietro lo stesso requireToken del router /api; il gate
   // READONLY route-level e la redazione token vivono dentro settingsRoutes.
-  api.use('/settings', settingsRoutes({ cfg, nodesPath, tokenStore, closeSessions, updater, runtimePort }));
+  api.use('/settings', settingsRoutes({
+    cfg, nodesPath, tokenStore, closeSessions, updater, runtimePort,
+    // Stesso adapter/coda dell'API Audio: Settings puo' fare solo la prova
+    // locale a frase fissa e lo stop sovrano, mai una seconda sintesi parallela.
+    audio: { adapter: audioAdapter, queue: audioQueue },
+  }));
   api.use('/diagnostics', diagnosticsRoutes({ diagnostics, readonly: proxyReadonly }));
   api.get('/topology', async (_req, res) => {
     try { res.json(await federation.collectLocalTopology({ nodesPath, cachePath: topologyCachePath })); }
@@ -367,6 +460,7 @@ function createServer(opts = {}) {
   });
   api.use('/route', federation.localRouter({
     nodesPath, localPort: () => (server && server.address() ? server.address().port : cfg.port), localCredential: () => tokenHolder.value, readonly: proxyReadonly,
+    hopSecret: () => hopSecret,
   }));
   api.get('/voice/status', (_req, res) => res.json({ serverSttConfigured: !!cfg.voiceUrl }));
   api.post('/voice/transcribe',
@@ -392,7 +486,7 @@ function createServer(opts = {}) {
   app.use('/api', api);
   app.use('/federation', federation.peerRouter({
     nodesPath, localPort: () => (server && server.address() ? server.address().port : cfg.port), localCredential: () => tokenHolder.value, readonly: proxyReadonly, version: VERSION,
-    fetchImpl: healthFetch,
+    fetchImpl: healthFetch, hopSecret: () => hopSecret,
     roles: () => require('./cli/commands.js').readRoles(cfg.configPath || configJsonPath()),
   }));
 

package/lib/settings/routes.js

@@ -45,6 +45,10 @@ const express = require('express');
 
 const nodesStore = require('../nodes/store.js');
 const nodeAliases = require('../nodes/aliases.js');
+const { setConsent: setAudioConsent, isConsent: isAudioConsent } = require('../audio/consent.js');
+const { describeCapability } = require('../audio/capability.js');
+const audioAdapters = require('../audio/adapters.js');
+const audioGroups = require('../audio/groups.js');
 const nodesCmds = require('../nodes/commands.js');
 const nodesTunnel = require('../nodes/tunnel.js');
 const peering = require('../nodes/peering.js');
@@ -63,10 +67,11 @@ const { createPairHandler } = require('./pairing-coordinator.js');
 const { publicPeeringRoutes } = require('./public-peering-routes.js');
 
 // Whitelist chiavi scrivibili di config.json via API (lista chiusa dal task B2).
-const CONFIG_KEYS = new Set(['roles', 'port', 'wizardDone', 'autoUpdate']);
+const CONFIG_KEYS = new Set(['roles', 'port', 'wizardDone', 'autoUpdate', 'alternateScreen']);
 const ROLE_KEYS = new Set(['client', 'node']);
 const ADD_KEYS = new Set(['name', 'ssh', 'sshPort', 'remotePort', 'localPort', 'keyPath', 'label']);
 const EDIT_KEYS = new Set(['label', 'ssh', 'sshPort', 'autostart', 'visibility', 'selected']);
+const LOCAL_AUDIO_TEST_TEXT = 'NexusCrew audio test.';
 
 // Default sensato per il "nome dispositivo" proposto nei form (pairing/invite).
 // NON usa ciecamente hostname: se l'hostname e' vuoto o 'localhost' (tipico di
@@ -165,6 +170,10 @@ function settingsRoutes(deps = {}) {
   const pendingPath = cfg.pendingPairingsPath || peering.defaultPendingPath(home);
   const platform = seams.platform || detectPlatform();
   const runtimePort = typeof deps.runtimePort === 'function' ? deps.runtimePort : () => cfg.port;
+  // Il server passa qui l'adapter e la coda REALI. Il fallback serve solo ai
+  // test unitari di Settings costruiti senza il server: non deve creare una
+  // seconda coda che dichiara un test riuscito ma non parla sul nodo vero.
+  const audioService = deps.audio && typeof deps.audio === 'object' ? deps.audio : null;
 
   const r = express.Router();
   r.use(express.json({ limit: '8kb' }));
@@ -233,6 +242,9 @@ function settingsRoutes(deps = {}) {
         service,
         version: VERSION,
         autoUpdate: updateStatus ? updateStatus.enabled : fileCfg.autoUpdate !== false,
+        // Valore effettivo: l'env mantiene la precedenza sul file e il runtime
+        // Fleet legge lo stesso oggetto cfg alla prossima creazione di cella.
+        alternateScreen: cfg.alternateScreen === true,
         // Nome dispositivo proposto per i form di pairing (etichetta umana, non
         // lo slug). La UI lo precompila e lascia editing libero.
         deviceName,
@@ -254,10 +266,10 @@ function settingsRoutes(deps = {}) {
         return send(res, 400, { error: 'body deve essere un oggetto JSON' });
       }
       for (const k of Object.keys(b)) {
-        if (!CONFIG_KEYS.has(k)) return send(res, 400, { error: `chiave non ammessa: "${k}" (whitelist: roles, port, wizardDone, autoUpdate)` });
+        if (!CONFIG_KEYS.has(k)) return send(res, 400, { error: `chiave non ammessa: "${k}" (whitelist: roles, port, wizardDone, autoUpdate, alternateScreen)` });
       }
       if (Object.keys(b).length === 0) {
-        return send(res, 400, { error: 'nessuna chiave da scrivere (whitelist: roles, port, wizardDone, autoUpdate)' });
+        return send(res, 400, { error: 'nessuna chiave da scrivere (whitelist: roles, port, wizardDone, autoUpdate, alternateScreen)' });
       }
       if (b.roles !== undefined) {
         if (!b.roles || typeof b.roles !== 'object' || Array.isArray(b.roles)) {
@@ -287,6 +299,9 @@ function settingsRoutes(deps = {}) {
       if (b.autoUpdate !== undefined && typeof b.autoUpdate !== 'boolean') {
         return send(res, 400, { error: 'autoUpdate deve essere boolean' });
       }
+      if (b.alternateScreen !== undefined && typeof b.alternateScreen !== 'boolean') {
+        return send(res, 400, { error: 'alternateScreen deve essere boolean' });
+      }
 
       // merge sul config esistente (preserva le chiavi non gestite qui)
       const { cfg: current } = readConfigFile(configPath);
@@ -298,14 +313,23 @@ function settingsRoutes(deps = {}) {
       if (b.port !== undefined) next.port = b.port;
       if (b.wizardDone !== undefined) next.wizardDone = b.wizardDone;
       if (b.autoUpdate !== undefined) next.autoUpdate = b.autoUpdate;
+      if (b.alternateScreen !== undefined) next.alternateScreen = b.alternateScreen;
       atomicWriteConfig(configPath, next);
       if (b.autoUpdate !== undefined && updater && typeof updater.setEnabled === 'function') {
         updater.setEnabled(b.autoUpdate);
       }
+      // Vale dalla prossima fleet up, mai retroattivamente; rispetta l'env che
+      // conserva la precedenza sul file per tutta la vita del processo.
+      if (b.alternateScreen !== undefined && process.env.NEXUSCREW_ALTERNATE_SCREEN === undefined) {
+        cfg.alternateScreen = b.alternateScreen;
+      }
 
       const out = {
         saved: true,
-        config: { roles: next.roles, port: next.port, wizardDone: next.wizardDone, autoUpdate: next.autoUpdate !== false },
+        config: {
+          roles: next.roles, port: next.port, wizardDone: next.wizardDone,
+          autoUpdate: next.autoUpdate !== false, alternateScreen: next.alternateScreen === true,
+        },
       };
       // Il server legge la porta SOLO allo startup: il cambio vale al prossimo
       // restart (contratto dichiarato nella risposta, la UI avvisa).
@@ -650,6 +674,23 @@ function settingsRoutes(deps = {}) {
         // the store/UI says private. Same-state OFF revokes first, then enters
         // the spec-aware start path without rewriting nodes.json.
         if (body.shared) {
+          // A same-state Share ON may target a supervisor stuck in "degraded"
+          // (reverse channel retrying on a fixed cadence after the initial
+          // budget). Accelerate ONLY a degraded supervisor that readTunnelState
+          // confirms we own (owned live pidfile + sidecar): force a local
+          // restart so the -R is retried immediately instead of waiting for the
+          // steady retry. A healthy tunnel stays idempotent, and we never revoke
+          // on the hub nor change the persisted shared intent in this branch.
+          const liveState = nodesTunnel.readTunnelState(home, name);
+          if (liveState && liveState.phase === 'degraded') {
+            // Reuse the normal restart transaction: it fails closed on a local
+            // spawn error and waits for the authenticated -L health probe before
+            // publishing Share again.  A process restart alone is never proof
+            // that the reverse channel is ready.
+            await ensureLocal({ restart: true });
+            await notifyHub(true);
+            return send(res, 200, { name, shared: true, unchanged: true, accelerated: true });
+          }
           await ensureLocal();
           await notifyHub(true);
           return send(res, 200, { name, shared: true, unchanged: true, reconciled: true });
@@ -709,6 +750,111 @@ function settingsRoutes(deps = {}) {
     if (!nodesStore.validLabel(label)) return send(res, 400, { error: 'label non valida (max 64 char, niente a capo)' });
     return applyNodeEdit(res, name, { label });
   });
+  // Consenso audio: proprieta' del nodo LOCALE, cioe' della macchina che
+  // suonerebbe, non di un record peer. Vive in un file dedicato e si muta solo
+  // da qui: `/audio/consent` non compare nella whitelist federation, quindi
+  // nessun peer puo' concedersi da remoto il permesso di far parlare un
+  // computer altrui. E' il terzo asse, separato da `shared` (pubblicazione) e da
+  // `visibility` (routing): nessuno dei due autorizza un suono fisico.
+  const audioCfg = {
+    home,
+    tokenPath: cfg && cfg.tokenPath,
+    audioConsentPath: cfg && cfg.audioConsentPath,
+    audioGroupsPath: cfg && cfg.audioGroupsPath,
+  };
+  const localAudioAdapter = () => {
+    if (audioService) return audioService.adapter || null;
+    return audioAdapters.createAdapter(audioAdapters.detectAdapter({}));
+  };
+  const localAudioQueue = () => (audioService ? audioService.queue || null : null);
+  const localAudioCapability = () => {
+    const consent = isAudioConsent(audioCfg, home) === true;
+    return describeCapability({ adapter: localAudioAdapter(), consent });
+  };
+  const emptyBody = (body) => body === undefined
+    || (body && typeof body === 'object' && !Array.isArray(body) && Object.keys(body).length === 0);
+  r.get('/audio', (_req, res) => {
+    try {
+      // Capability redatta: id logico dell'adapter e limiti dichiarati, mai il
+      // path del binario e mai l'elenco delle voci di sistema.
+      return send(res, 200, localAudioCapability());
+    } catch (_) {
+      return send(res, 500, { error: 'stato audio non leggibile' });
+    }
+  });
+  r.patch('/audio/consent', mutGate, (req, res) => {
+    const consent = req.body && req.body.consent;
+    if (typeof consent !== 'boolean') {
+      return send(res, 400, { error: 'body non valido: atteso {consent:boolean}' });
+    }
+    try {
+      setAudioConsent(audioCfg, consent, home);
+      return send(res, 200, localAudioCapability());
+    } catch (_) {
+      return send(res, 500, { error: 'scrittura consenso audio non riuscita' });
+    }
+  });
+  // Prova esplicita dal pannello Settings. Non e' `nc_speak`: non accetta testo,
+  // target, cella o origine dal browser e non e' inoltrabile via federazione.
+  // Usa solo una frase fissa, il consenso del nodo e la sua coda reale; un 200
+  // descrive l'esito onesto dell'azione, NON prova che qualcuno abbia sentito.
+  r.post('/audio/test', mutGate, (req, res) => {
+    if (!emptyBody(req.body)) return send(res, 400, { error: 'body non valido: nessun campo ammesso' });
+    try {
+      const capability = localAudioCapability();
+      if (capability.consent !== true) return send(res, 200, { status: 'refused', reason: 'consent' });
+      const queue = localAudioQueue();
+      if (capability.installed !== true || !queue || typeof queue.enqueue !== 'function') {
+        return send(res, 200, { status: 'refused', reason: 'no-adapter' });
+      }
+      const result = queue.enqueue({
+        utteranceId: `settings-${crypto.randomUUID()}`,
+        text: LOCAL_AUDIO_TEST_TEXT,
+        urgency: 'normal',
+      });
+      return send(res, 200, {
+        status: result && result.status === 'accepted' ? 'accepted' : 'refused',
+        ...(result && result.reason ? { reason: String(result.reason).slice(0, 64) } : {}),
+      });
+    } catch (_) {
+      return send(res, 500, { error: 'prova audio locale non riuscita' });
+    }
+  });
+  // Stop locale sovrano: resta disponibile anche in READONLY. Non richiede rete,
+  // origin MCP o receipt, perche' zittire il dispositivo non deve dipendere da
+  // chi l'aveva fatto parlare. Ferma tutti i test/enunciati ancora in coda.
+  r.post('/audio/stop', (req, res) => {
+    if (!emptyBody(req.body)) return send(res, 400, { error: 'body non valido: nessun campo ammesso' });
+    try {
+      const queue = localAudioQueue();
+      const stopped = !!(queue && typeof queue.stopAll === 'function' && queue.stopAll());
+      return send(res, 200, { status: 'accepted', stopped });
+    } catch (_) {
+      return send(res, 500, { error: 'stop audio locale non riuscito' });
+    }
+  });
+  // Gruppi dell'ORIGINE: configurazione locale, separata dal consenso di ogni
+  // endpoint. Non e' nella whitelist federation e una lista non puo' far
+  // parlare un nodo senza il suo consenso/liveness al momento della consegna.
+  r.get('/audio/groups', (_req, res) => {
+    try { return send(res, 200, { groups: audioGroups.listGroups(audioCfg, home) }); }
+    catch (_) { return send(res, 500, { error: 'gruppi audio non leggibili' }); }
+  });
+  r.put('/audio/groups/:name', mutGate, (req, res) => {
+    const body = req.body;
+    if (!body || typeof body !== 'object' || Array.isArray(body)
+      || Object.keys(body).some((key) => !['targets', 'mode'].includes(key))) {
+      return send(res, 400, { error: 'body non valido: attesi targets e mode' });
+    }
+    try { return send(res, 200, { group: audioGroups.saveGroup(audioCfg, String(req.params.name || ''), body, home) }); }
+    catch (_) { return send(res, 400, { error: 'gruppo audio non valido' }); }
+  });
+  r.delete('/audio/groups/:name', mutGate, (req, res) => {
+    try {
+      const removed = audioGroups.removeGroup(audioCfg, String(req.params.name || ''), home);
+      return removed ? send(res, 200, { removed: true }) : send(res, 404, { error: 'gruppo audio non trovato' });
+    } catch (_) { return send(res, 400, { error: 'nome gruppo audio non valido' }); }
+  });
 
   // Viewer-local aliases for routed nodes. These routes are local-only and do
   // not mutate the peer identity, route, label, or federated topology.

package/lib/tmux/lifecycle.js

@@ -2,6 +2,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFile } = require('node:child_process');
+const { alternateScreenArgs, minimalEnv, tmuxExec } = require('../fleet/launch.js');
 
 // Preset allowlistati (audit F1): il client sceglie un NOME, mai un comando.
 // Estendibili da config.json `sessionPresets` (name -> array argv di stringhe).
@@ -52,9 +53,25 @@ function buildCreateArgs(name, realCwd, preset, extraPresets) {
 
 function httpError(status, msg) { const e = new Error(msg); e.status = status; return e; }
 
-async function createSession(tmuxBin, { name, cwd, preset }, { home, presets, ensureProtection } = {}) {
+// Best effort per la sola sessione PWA appena creata. Riusa il builder Fleet:
+// target exact-match, opzione window-local e hook per le finestre successive.
+// Un tmux che rifiuta l'opzione non deve mai trasformare una creazione riuscita
+// in un errore HTTP; nessuna opzione globale viene emessa.
+async function configureAlternateScreen(tmuxBin, name, alternateScreen, log) {
+  const steps = alternateScreenArgs(name, alternateScreen);
+  if (!steps) return;
+  const warn = typeof log === 'function' ? log : console.warn;
+  for (const args of steps) {
+    const configured = await tmuxExec(tmuxBin, args, { env: minimalEnv(), timeoutMs: 2000 });
+    if (configured.err) warn(`session alternate-screen setup failed for ${name}; continuing`);
+  }
+}
+
+async function createSession(tmuxBin, { name, cwd, preset }, {
+  home, presets, ensureProtection, alternateScreen, log,
+} = {}) {
   if (typeof ensureProtection === 'function') await ensureProtection();
-  return new Promise((resolve, reject) => {
+  await new Promise((resolve, reject) => {
     if (!validSessionName(name)) return reject(httpError(400, 'nome sessione non valido'));
     // Il namespace cloud-* e' delle celle fleet (audit finale #1): una generica
     // con quel prefisso occuperebbe il binding per-nome e sarebbe poi 409 al kill.
@@ -71,6 +88,7 @@ async function createSession(tmuxBin, { name, cwd, preset }, { home, presets, en
       resolve();
     });
   });
+  await configureAlternateScreen(tmuxBin, name, alternateScreen, log);
 }
 
 async function killSession(tmuxBin, name, { ensureProtection } = {}) {
@@ -86,4 +104,7 @@ async function killSession(tmuxBin, name, { ensureProtection } = {}) {
   });
 }
 
-module.exports = { PRESETS, validSessionName, resolveCwd, isProtectedSession, buildCreateArgs, createSession, killSession };
+module.exports = {
+  PRESETS, validSessionName, resolveCwd, isProtectedSession, buildCreateArgs,
+  configureAlternateScreen, createSession, killSession,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.8.39",
+  "version": "0.8.41",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {

package/skills/nexuscrew-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nexuscrew-agent
-description: Use when an AI agent connected to NexusCrew must notify or ask the human, inspect runtime or deck context, list authorized Fleet cells, message an exact active cell, read its inbox, deliver a file, or recover from local tmux messages that remain unsubmitted or garbled. Prefer nc_notify, nc_ask, nc_status, nc_deck, nc_cells, nc_send_cell, nc_inbox, and nc_send_file; use bundled tmux/file helpers only as a declared compatibility fallback.
+description: Use when an AI agent connected to NexusCrew must notify or ask the human, inspect runtime or deck context, list authorized Fleet cells, message an exact active cell, read its inbox, deliver a file, recover from local tmux messages that remain unsubmitted or garbled, or when a drag in the web terminal does not scroll a full-screen TUI. Prefer nc_notify, nc_ask, nc_status, nc_deck, nc_cells, nc_send_cell, nc_inbox, and nc_send_file; use bundled tmux/file helpers only as a declared compatibility fallback.
 ---
 
 # NexusCrew Agent I/O
@@ -91,6 +91,33 @@ It does: `load-buffer` → `paste-buffer -p` (bracketed paste) → burst-flush (
 tmux capture-pane -t <session> -p | tail -8   # see the text / a running state
 ```
 
+## Terminal scrolling (NexusCrew-managed tmux)
+
+A drag or wheel in the NexusCrew web terminal browses the tmux history through
+copy-mode. That works only while the pane is on the normal screen. A full-screen
+TUI — Claude Code, Codex, Agy, `vim`, `less`, `htop` — renders in the terminal's
+**alternate buffer**, which has no scrollback: copy-mode has nothing to scroll, so
+the gesture does nothing. On a phone, where the drag is the only scroll gesture,
+the terminal looks frozen.
+
+NexusCrew applies `alternate-screen off` **per session** when it creates a
+managed Fleet session or a PWA session. No global tmux option or `~/.tmux.conf` edit is needed:
+tmux then ignores `smcup`/`rmcup` for that session, TUI output stays on the
+normal screen, the transcript flows into tmux history, and drag/wheel scrolling
+work. The setting is also applied to windows created later in that session.
+
+- It applies only to future NexusCrew-created sessions. A running or unmanaged
+  pane remains unchanged; never restart a Fleet cell just to change it.
+- To opt out, set `alternateScreen: true` in NexusCrew's local `config.json` or
+  start the service with `NEXUSCREW_ALTERNATE_SCREEN=1`.
+- Verify on a pane that is running a TUI:
+  `tmux display-message -p -t '=<session>:' '#{alternate_on}'` must print `0`.
+- Trade-off: after quitting `vim`/`less`/`htop` the last screen stays on display
+  instead of being restored.
+- Full-screen redraws consume history. Keep a generous user-owned
+  `history-limit` (100000 is a good default); `nexuscrew doctor` warns below
+  10000 and suggests `set -g history-limit 100000`, but never writes it.
+
 ## Quick reference
 
 | Goal | Do this |
@@ -106,6 +133,7 @@ tmux capture-pane -t <session> -p | tail -8   # see the text / a running state
 | Send a prompt/command to a session | `nc-send <session> "text"` |
 | Queue text without running it | `nc-send <session> --no-submit "text"` |
 | Confirm a send worked | `tmux capture-pane -t <session> -p | tail` |
+| Make a new managed terminal scrollable on a full-screen TUI | NexusCrew default; verify `#{alternate_on}` is `0` |
 
 ## Common mistakes
 
@@ -116,3 +144,4 @@ tmux capture-pane -t <session> -p | tail -8   # see the text / a running state
 - **Delivering to a guessed session name** → file lands in an orphan folder with no badge. Use `nc-deliver` (it reads the real session).
 - **Sending to an ambiguous cell name** → call `nc_cells` and use the full owner-qualified ID.
 - **Calling `submitted` a completed task** → it is only a transport receipt; require an explicit result callback.
+- **Treating a dead scroll gesture as a web-terminal bug** → the pane is in the alternate buffer. Check whether it predates the NexusCrew setting or opted out with `alternateScreen:true`; never send raw page keys to a TUI to work around it.