@mmmbuto/nexuscrew 0.8.39 → 0.8.41

package/lib/fleet/managed.js

@@ -60,7 +60,11 @@ const ALIBABA_PI_MODELS = Object.freeze([
 ]);
 
 const CUSTOM_KEYS = ['displayName', 'protocol', 'baseUrl', 'envKey', 'providerId'];
-const MANAGED_KEYS = new Set(['client', 'provider', 'credentialProfile', 'model', 'permissionPolicy', ...CUSTOM_KEYS]);
+const MANAGED_KEYS = new Set(['client', 'provider', 'credentialProfile', 'model', 'permissionPolicy', 'credentialSourcePolicy', ...CUSTOM_KEYS]);
+// Explicit credential source policy. Default 'auto' preserves the legacy
+// resolution order (runtime -> store -> shell -> key files -> legacy) so a
+// pre-WP1 fleet.json migrates no-op: no existing cell changes resolution.
+const CREDENTIAL_SOURCES = Object.freeze(['environment', 'nexuscrew-store', 'auto']);
 const CLIENT_LABELS = Object.freeze({ claude: 'Claude Code', codex: 'Codex', 'codex-vl': 'Codex-VL', pi: 'Pi', agy: 'Agy', shell: 'Shell' });
 const PROVIDER_ID_RE = /^[a-z][a-z0-9_-]{0,31}$/;
 
@@ -167,7 +171,13 @@ function normalizeManagedSpec(value) {
   const permissionPolicy = value.permissionPolicy === undefined ? (profile.client === 'claude' ? 'unsafe' : 'standard') : value.permissionPolicy;
   if (permissionPolicy !== 'standard' && permissionPolicy !== 'unsafe') return null;
   if ((value.client === 'pi' || value.client === 'shell') && permissionPolicy !== 'standard') return null;
+  const credentialSourcePolicy = value.credentialSourcePolicy === undefined ? 'auto' : value.credentialSourcePolicy;
+  if (!CREDENTIAL_SOURCES.includes(credentialSourcePolicy)) return null;
   const out = { client: profile.client, provider: profile.provider, model, permissionPolicy };
+  // 'auto' is the default and stays ABSENT from the normalized spec, so a legacy
+  // fleet.json (no credentialSourcePolicy) migrates truly no-op: no added field,
+  // no change in resolution. Explicit environment|nexuscrew-store are recorded.
+  if (credentialSourcePolicy !== 'auto') out.credentialSourcePolicy = credentialSourcePolicy;
   if (profile.credentialProfile) out.credentialProfile = profile.credentialProfile;
   if (profile.credentialEnv) {
     const envKey = typeof value.envKey === 'string' && value.envKey.trim()
@@ -416,10 +426,20 @@ function credentialSources(cfg, home) {
 function credential(profile, spec, cfg, home) {
   if (profile.auth === 'login' || profile.auth === 'none') return { envKey: profile.auth, value: '', source: profile.auth };
   const envKey = profile.auth === 'dynamic' ? spec.envKey : profile.auth;
+  const policy = spec && CREDENTIAL_SOURCES.includes(spec.credentialSourcePolicy) ? spec.credentialSourcePolicy : 'auto';
   const sources = credentialSources(cfg, home);
   // The fixed shell file is already the user's environment source. Values are
   // consumed only in memory and passed to the selected child; never persisted
   // in fleet.json, service files, API responses or logs.
+  if (policy === 'environment') {
+    if (sources.runtime[envKey]) return { envKey, value: sources.runtime[envKey], source: 'environment' };
+    return { envKey, value: '', source: 'missing' };
+  }
+  if (policy === 'nexuscrew-store') {
+    if (sources.local[envKey]) return { envKey, value: sources.local[envKey], source: 'nexuscrew-store' };
+    return { envKey, value: '', source: 'missing' };
+  }
+  // auto: legacy resolution order (runtime -> store -> shell -> keys -> legacy).
   if (sources.runtime[envKey]) return { envKey, value: sources.runtime[envKey], source: 'environment' };
   if (sources.local[envKey]) return { envKey, value: sources.local[envKey], source: 'local' };
   if (sources.shell[envKey]) return { envKey, value: sources.shell[envKey], source: 'compatibility' };
@@ -430,6 +450,31 @@ function credential(profile, spec, cfg, home) {
   return { envKey, value: '', source: 'missing' };
 }
 
+// The profile's "owned" env set. When the credential source is the local store,
+// the child environment must not inherit any of these from the runtime: the
+// entire set is enumerated and neutralized (unset), never just envKey. For
+// Anthropic-compatible (claude.*) clients the set is the ANTHROPIC_* triple;
+// every other client keeps the single profile envKey.
+function credentialEnvNeutralizeSet(profile) {
+  if (!profile) return [];
+  if (profile.client === 'claude') return ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY'];
+  const auth = profile.auth;
+  const envKey = auth && auth !== 'dynamic' && auth !== 'login' && auth !== 'none'
+    ? auth : (profile.defaultEnvKey || '');
+  return envKey ? [envKey] : [];
+}
+
+// Apply nexuscrew-store neutralization to a composed child env: keys of the
+// profile set that carry no NexusCrew-injected value are UNSET (deleted), never
+// left as an empty string. 'auto'/'environment' are unchanged (legacy behavior).
+function applyStoreNeutralization(env, spec, profile) {
+  if (!env || !spec || spec.credentialSourcePolicy !== 'nexuscrew-store') return env;
+  for (const k of credentialEnvNeutralizeSet(profile)) {
+    if (env[k] === undefined || env[k] === '') delete env[k];
+  }
+  return env;
+}
+
 let ollamaCache = { at: 0, models: [] };
 async function discoverOllamaModels(opts = {}) {
   const now = Date.now(); const ttl = opts.ttlMs === undefined ? 30000 : opts.ttlMs;
@@ -527,6 +572,7 @@ function describeManaged(spec, cfg = {}) {
     credentialProfile: normalized.credentialProfile || '', model: normalized.model,
     permissionPolicy: normalized.permissionPolicy, protocol: normalized.protocol || profile.protocol,
     endpoint: normalized.baseUrl || profile.endpoint || '', auth: cred.envKey, authConfigured,
+    credentialSourcePolicy: normalized.credentialSourcePolicy || 'auto',
     credentialSource: authConfigured ? cred.source : 'missing',
     configured, models: [...(profile.models || [])], defaultModel: profile.model || '',
     binary: binary || '', displayName: normalized.displayName || profile.label,
@@ -814,6 +860,10 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     if (cell?.prompt) args.push('--prompt-interactive');
   }
   if (spec.client !== 'shell' && cell?.prompt) args.push(cell.prompt);
+  // nexuscrew-store source: neutralize the profile's env set in the composed
+  // child env (unset, never empty), so the runtime cannot leak credentials that
+  // the local store is meant to own.
+  applyStoreNeutralization(env, spec, profile);
   let command = info.binary;
   if (needsExplicitNode(info.binary, cfg.platform || process.platform, cfg.env || process.env)) {
     command = cfg.nodeExecPath || process.execPath;
@@ -841,10 +891,11 @@ function publicCatalog() {
 module.exports = {
   CATALOG, OLLAMA_CLOUD_MODELS, OLLAMA_CONTEXT, ALIBABA_TOKEN_PLAN_MODELS,
   ALIBABA_CODEX_MODELS, ALIBABA_TOKEN_PLAN_CONTEXT, ALIBABA_PI_MODELS,
-  CLIENT_LABELS, normalizeManagedSpec,
+  CLIENT_LABELS, normalizeManagedSpec, profileFor,
   defaultDefinitions, defaultShellEngine, defaultAgyEngine, describeManaged, describeCatalogCredential, discoverOllamaModels, resolveManagedEngine, needsExplicitNode,
   discoverPiModels, parseEnvFile, parseProviderShellFile, findBinary, publicCatalog, writePiProviderExtension,
   providerKeyPaths, parseProviderKeyFiles, credentialSources, credential,
+  credentialEnvNeutralizeSet, applyStoreNeutralization,
   ensureKimiClaudeConfig, ensureAlibabaClaudeConfig, resolveInteractiveShell,
   shellLoginArgs, shellConfiguredCommandArgs, ENV_KEY_RE,
 };

package/lib/fleet/provider.js

@@ -13,6 +13,12 @@ function disabled(reason) {
 }
 
 async function selectProvider(cfg = {}) {
+  // Seam esplicito per i test: permette di far girare il server REALE con uno
+  // stato Fleet controllato, senza tmux ne' processi. Esiste perche' i confini
+  // che dipendono dalle celle attive (l'origine di Audio Share) vanno provati
+  // sul server vero: un test che inietta le dipendenze nel router non si
+  // accorgerebbe mai di un cablaggio sbagliato.
+  if (cfg.fleetSeam) return { mode: 'seam', reason: 'fleet iniettata (seam di test)', fleet: cfg.fleetSeam };
   if (cfg.fleetEnabled === false) return disabled('fleet disabilitata (fleetEnabled=false)');
   if (cfg.builtinEnabled === false) return disabled('fleet builtin disabilitata (builtinEnabled=false)');
   const fleet = await createBuiltinFleet({ ...cfg, fleetProviderReason: 'NexusCrew builtin fleet' });

package/lib/fleet/runtime.js

@@ -21,7 +21,7 @@ const {
 } = require('./managed.js');
 const {
   httpError, minimalEnv, tmuxExec,
-  composeClientInvocation,
+  composeClientInvocation, alternateScreenArgs,
   waitAlive, waitStablePane, injectPrompt,
   redactSecrets, sanitizeEarlyDiagnostic,
 } = require('./launch.js');
@@ -246,6 +246,19 @@ function createBuiltinRuntime(ctx) {
       throw httpError(dup ? 409 : 500, why, null,
         { phase: 'new-session', code: dup ? 'SESSION_DUPLICATE' : 'NEW_SESSION_FAILED' });
     }
+    // Best effort per la sola sessione appena creata: non tocchiamo mai
+    // ~/.tmux.conf, opzioni globali o sessioni preesistenti. Un tmux che non
+    // accetta una delle opzioni non deve impedire l'avvio della cella.
+    const alternateSteps = alternateScreenArgs(cell.tmuxSession, cfg.alternateScreen);
+    if (alternateSteps) {
+      for (const args of alternateSteps) {
+        const configured = await tmuxExec(tmuxBin, args, { env: minimalEnv(), timeoutMs: 2000 });
+        if (configured.err) {
+          const log = typeof cfg.log === 'function' ? cfg.log : console.warn;
+          log(`fleet alternate-screen setup failed for ${cell.id}; continuing`);
+        }
+      }
+    }
     const createdIds = create.stdout.trim().split('\n')[0].split('\t');
     const sessionId = /^\$[0-9]+$/.test(createdIds[0] || '') ? createdIds[0] : '';
     const windowId = /^@[0-9]+$/.test(createdIds[1] || '') ? createdIds[1] : '';

package/lib/mcp/server.js

@@ -20,10 +20,12 @@
 const readline = require('node:readline');
 const crypto = require('node:crypto');
 const os = require('node:os');
+const path = require('node:path');
 const { execFile } = require('node:child_process');
 const { loadConfig } = require('../config.js');
 const { readTokenSafe } = require('../auth/token.js');
 const { isValidSession } = require('../files/store.js');
+const { loadOrCreateBridgeSecret, signedHeaders } = require('../audio/bridge-auth.js');
 const VERSION = require('../../package.json').version;
 const MCP_COMPANIONS = require('../../mcp-companions.json');
 const { TOOLS, IDENTITY_CODE, IDENTITY_REMEDIATION } = require('./tools.js');
@@ -162,17 +164,39 @@ function createMcpServer(opts = {}) {
     throw new Error('token NexusCrew non leggibile: il server e\' inizializzato? (nexuscrew init)');
   }
 
-  async function api(method, apiPath, body) {
+  // Segreto del bridge: file 0600 accanto al token, distinto dal token stesso.
+  // Serve dove il Bearer non basta — Audio Share — perche' il Bearer prova solo
+  // "qualcuno in loopback ce l'ha", non "questa e' la cella X".
+  const bridgeKeyPath = () => cfg.audioBridgeSecretPath || path.join(path.dirname(cfg.tokenPath), 'audio-bridge.key');
+
+  // `opts.signedSession` attiva la firma HMAC del bridge: copre metodo, path,
+  // sessione, timestamp, nonce e i BYTE del body effettivamente inviati. Per
+  // questo il payload viene serializzato UNA volta sola e riusato: firmare un
+  // JSON e spedirne un altro, anche solo con un ordine di chiavi diverso,
+  // produrrebbe una firma valida per un corpo che il server non vede mai.
+  async function api(method, apiPath, body, opts = {}) {
     const token = readToken();
+    const payload = body !== undefined ? JSON.stringify(body) : undefined;
+    let signed = {};
+    if (opts.signedSession) {
+      try {
+        signed = signedHeaders(loadOrCreateBridgeSecret(bridgeKeyPath()), {
+          method, path: apiPath, session: opts.signedSession, rawBody: payload === undefined ? '' : payload,
+        });
+      } catch (_) {
+        throw new Error('segreto bridge audio non leggibile: il server e\' inizializzato? (nexuscrew init)');
+      }
+    }
     let r;
     try {
       r = await fetchImpl(`${baseUrl}${apiPath}`, {
         method,
         headers: {
           authorization: `Bearer ${token}`,
-          ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+          ...signed,
+          ...(payload !== undefined ? { 'content-type': 'application/json' } : {}),
         },
-        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        ...(payload !== undefined ? { body: payload } : {}),
         signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
       });
     } catch (e) {

package/lib/mcp/tools.js

@@ -496,6 +496,148 @@ const TOOLS = [
       return out;
     },
   },
+  {
+    name: 'nc_speak',
+    description: 'Speak un utterance audio verso un nodo target (exact instanceId). Ritorna un receipt caller-scoped con status per-endpoint (refused|unreachable|accepted|spoken|unknown) e attribution; MAI text/lang/voice o aggregate success. L\'origin genera un utteranceId immutabile se omesso.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'exact target node instanceId (32 hex)' },
+        text: { type: 'string', description: 'utterance text (bounded)' },
+        lang: { type: 'string', description: 'BCP-47 lang hint (optional)' },
+        voice: { type: 'string', description: 'voice id hint (optional)' },
+        urgency: { type: 'string', enum: ['normal', 'high'], description: 'high urgency non bypassa i rate limit' },
+        utteranceId: { type: 'string', description: 'immutable id (generato se omesso)' },
+      },
+      required: ['target', 'text'],
+    },
+    async handler(args, ctx) {
+      const target = argString(args, 'target', { required: true, max: 32 });
+      const text = argString(args, 'text', { required: true, max: 320 });
+      const lang = argString(args, 'lang', { max: 35 });
+      const voice = argString(args, 'voice', { max: 64 });
+      if (args.urgency !== undefined && args.urgency !== 'normal' && args.urgency !== 'high') {
+        throw new Error('urgency deve essere "normal" o "high"');
+      }
+      const urgency = args.urgency === 'high' ? 'high' : 'normal';
+      const utteranceId = argString(args, 'utteranceId', { max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak', identity.code);
+      // La sessione NON viaggia nel body: sarebbe una dichiarazione, e una
+      // dichiarazione e' falsificabile da chiunque abbia il token della UI.
+      // Viaggia dentro la firma HMAC del bridge, che il server verifica prima di
+      // attribuire l'enunciato a una cella.
+      const payload = { target, text, urgency, ...(lang ? { lang } : {}), ...(voice ? { voice } : {}), ...(utteranceId ? { utteranceId } : {}) };
+      const receipt = await ctx.api('POST', '/api/audio/speak', payload, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_status',
+    description: 'Interroga lo status di uno speak per utteranceId (read-only). Ritorna il receipt caller-scoped redacted (status/reason/attribution); MAI text/lang/voice/secret.',
+    inputSchema: {
+      type: 'object',
+      properties: { utteranceId: { type: 'string', description: 'utterance id da interrogare' } },
+      required: ['utteranceId'],
+    },
+    annotations: { readOnlyHint: true },
+    async handler(args, ctx) {
+      const utteranceId = argString(args, 'utteranceId', { required: true, max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_status', identity.code);
+      const receipt = await ctx.api('GET', `/api/audio/speak/status/${encodeURIComponent(utteranceId)}`, undefined, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_stop',
+    description: 'Ferma un enunciato su un nodo target. Con utteranceId ferma quello specifico (solo se e\' del chiamante), senza utteranceId ferma tutto sul target. Lo stop locale del nodo resta sovrano e non dipende da questa chiamata.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'exact target node instanceId (32 hex)' },
+        utteranceId: { type: 'string', description: 'enunciato da fermare; omesso = tutti gli enunciati del target' },
+      },
+      required: ['target'],
+    },
+    async handler(args, ctx) {
+      const target = argString(args, 'target', { required: true, max: 32 });
+      const utteranceId = argString(args, 'utteranceId', { max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_stop', identity.code);
+      const receipt = await ctx.api('POST', '/api/audio/stop', {
+        target, ...(utteranceId ? { utteranceId } : {}),
+      }, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_group',
+    description: 'Speak verso un gruppo audio locale nominato. Il gruppo espande solo instanceId esatti: primary-failover prova un endpoint alla volta, fanout e esplicito. Ritorna subito un receipt per endpoint; usa nc_speak_group_status per gli aggiornamenti. Un gruppo non concede consenso e non aggira liveness/ACL del target.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        group: { type: 'string', description: 'nome del gruppo audio locale (a-z, 0-9, trattini)' },
+        text: { type: 'string', description: 'utterance text (bounded)' },
+        lang: { type: 'string', description: 'BCP-47 lang hint (optional)' },
+        voice: { type: 'string', description: 'voice id hint (optional)' },
+        urgency: { type: 'string', enum: ['normal', 'high'], description: 'high urgency non bypassa i rate limit' },
+        utteranceId: { type: 'string', description: 'immutable id (generato se omesso)' },
+      },
+      required: ['group', 'text'],
+    },
+    async handler(args, ctx) {
+      const group = argString(args, 'group', { required: true, max: 32 });
+      const text = argString(args, 'text', { required: true, max: 320 });
+      const lang = argString(args, 'lang', { max: 35 });
+      const voice = argString(args, 'voice', { max: 64 });
+      if (args.urgency !== undefined && args.urgency !== 'normal' && args.urgency !== 'high') {
+        throw new Error('urgency deve essere "normal" o "high"');
+      }
+      const urgency = args.urgency === 'high' ? 'high' : 'normal';
+      const utteranceId = argString(args, 'utteranceId', { max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_group', identity.code);
+      const receipt = await ctx.api('POST', '/api/audio/groups/speak', {
+        group, text, urgency,
+        ...(lang ? { lang } : {}), ...(voice ? { voice } : {}), ...(utteranceId ? { utteranceId } : {}),
+      }, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_group_status',
+    description: 'Interroga lo status per-endpoint di un gruppo audio (read-only). Il receipt e caller-scoped e non contiene testo, lingua, voce o successi aggregati.',
+    inputSchema: {
+      type: 'object',
+      properties: { utteranceId: { type: 'string', description: 'utterance id del gruppo' } },
+      required: ['utteranceId'],
+    },
+    annotations: { readOnlyHint: true },
+    async handler(args, ctx) {
+      const utteranceId = argString(args, 'utteranceId', { required: true, max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_group_status', identity.code);
+      const receipt = await ctx.api('GET', `/api/audio/groups/status/${encodeURIComponent(utteranceId)}`, undefined, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_group_stop',
+    description: 'Ferma un gruppo audio per utteranceId: blocca i candidati non ancora tentati e invia Stop a ogni endpoint gia ammesso. Lo Stop locale del nodo resta sovrano anche offline.',
+    inputSchema: {
+      type: 'object',
+      properties: { utteranceId: { type: 'string', description: 'utterance id del gruppo da fermare' } },
+      required: ['utteranceId'],
+    },
+    async handler(args, ctx) {
+      const utteranceId = argString(args, 'utteranceId', { required: true, max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_group_stop', identity.code);
+      const receipt = await ctx.api('POST', '/api/audio/groups/stop', { utteranceId }, { signedSession: session });
+      return { receipt };
+    },
+  },
 ];
 
 module.exports = {

package/lib/nodes/tunnel-supervisor.js

@@ -21,6 +21,17 @@ const ownershipGraceMs = Number.isFinite(ownershipGraceRaw) && ownershipGraceRaw
 const reverseFailureMaxRaw = Number(process.env.NEXUSCREW_TUNNEL_REVERSE_FAILURE_MAX || 8);
 const reverseFailureMax = Number.isInteger(reverseFailureMaxRaw) && reverseFailureMaxRaw >= 1
   ? Math.min(reverseFailureMaxRaw, 32) : 8;
+// Once the initial reverse-forward budget is exhausted the supervisor does NOT
+// die: it stays "degraded" and retries at the fixed production cadence of 60s,
+// so a transient reverse listener on the hub (e.g. a mobile reconnect) heals on
+// its own without an OFF/ON.  A short cadence is a test-only seam, never a
+// production runtime override: otherwise a bad environment value could recreate
+// the retry storm that this breaker is meant to prevent.
+const steadyRetryTestMode = process.env.NEXUSCREW_TUNNEL_TEST_MODE === '1';
+const steadyRetryMsRaw = Number(steadyRetryTestMode ? (process.env.NEXUSCREW_TUNNEL_STEADY_RETRY_MS || 60000) : 60000);
+const steadyRetryMinMs = steadyRetryTestMode ? 1 : 60000;
+const steadyRetryMs = Number.isFinite(steadyRetryMsRaw) && steadyRetryMsRaw >= steadyRetryMinMs
+  ? Math.min(steadyRetryMsRaw, 120000) : 60000;
 if (!sshBin || !statePath || !pidPath || !runId) process.exit(2);
 
 let child = null;
@@ -92,6 +103,7 @@ function probeForward(expectedChild) {
     if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
     if (ready) {
       attempt = 0;
+      reverseFailures = 0;
       logEvent(`forward ready stableMs=${stableMs}`);
       if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'tcp-forward' })) stop();
       return;
@@ -137,14 +149,28 @@ function scheduleRetry(detail) {
   retryTimer = setTimeout(run, delayMs);
 }
 
-function terminalFailure(diagnosis) {
+// Bounded, attributable degraded state. The supervisor stays alive, advertises
+// the reverse failure class plus the negotiated reversePort and the honest
+// remote-listener attribution (unknown without hub privilege), then retries on
+// a fixed cadence. It never exits on a reverse-forward failure: the tunnel
+// self-heals when the channel frees up.
+function enterDegraded(diagnosis) {
+  if (stopping) return finish();
   const safe = diagnosis || { code: 'reverse-forward-failed', detail: 'canale inverso non disponibile' };
-  logEvent(`ssh terminal failure code=${safe.code} attempts=${reverseFailures}`);
-  writeState('failed', {
+  if (reverseFailures > reverseFailureMax) reverseFailures = reverseFailureMax;
+  // `ownsGeneration()` only proves that THIS local supervisor owns its pidfile;
+  // it cannot identify the process holding a listener on the hub.  Never turn
+  // local pidfile ownership into a false remote-listener attribution.
+  const ownership = 'unknown';
+  logEvent(`ssh degraded code=${safe.code} reversePort=${reversePort || 'none'} ownership=${ownership} failures=${reverseFailures} steadyRetryMs=${steadyRetryMs}`);
+  if (!writeState('degraded', {
     code: safe.code, detail: safe.detail,
-    ...(safe.hint ? { hint: safe.hint } : {}), terminal: true,
-  });
-  process.exit(0);
+    ...(safe.hint ? { hint: safe.hint } : {}),
+    reversePort, ownership, steadyRetryMs, terminal: false,
+  })) return stop();
+  // Keep the backoff counter honest for observers; the degraded retry is fixed.
+  if (attempt < reverseFailureMax) attempt = reverseFailureMax;
+  retryTimer = setTimeout(run, steadyRetryMs);
 }
 
 function run() {
@@ -176,7 +202,7 @@ function run() {
     const reverseFailure = diagnosis && ['reverse-forward-bind', 'reverse-forward-failed'].includes(diagnosis.code);
     if (reverseFailure) {
       reverseFailures += 1;
-      if (reverseFailures >= reverseFailureMax) return terminalFailure(diagnosis);
+      if (reverseFailures >= reverseFailureMax) return enterDegraded(diagnosis);
     } else {
       reverseFailures = 0;
     }

package/lib/nodes/tunnel.js

@@ -290,6 +290,19 @@ function readTunnelState(home, name) {
       const owned = state.supervisorPid === meta.pid && (!meta.runId || state.runId === meta.runId);
       if (!owned) return { status: 'down', pid: meta.pid, since: meta.startTs || null, reason: 'starting' };
       if (state.status === 'failed' && state.terminal === true) return terminalState();
+      if (state.status === 'degraded') {
+        return {
+          status: 'down', phase: 'degraded', reason: 'degraded', pid: meta.pid, since: meta.startTs || null,
+          ...(typeof state.code === 'string' ? { code: state.code } : {}),
+          ...(typeof state.detail === 'string' ? { detail: state.detail } : {}),
+          ...(typeof state.hint === 'string' ? { hint: state.hint } : {}),
+          ...(Number.isInteger(state.reversePort) ? { reversePort: state.reversePort } : {}),
+          ...(typeof state.ownership === 'string' ? { ownership: state.ownership } : {}),
+          ...(Number.isInteger(state.attempt) ? { attempt: state.attempt } : {}),
+          ...(Number.isFinite(state.steadyRetryMs) ? { retryInMs: state.steadyRetryMs } : {}),
+          ...(transport ? { transport } : {}),
+        };
+      }
       if (state.status === 'transport-ready' || state.status === 'up') {
         return { status: 'up', phase: 'transport-ready', pid: meta.pid, since: meta.startTs || null,
           ...(Number.isInteger(state.attempt) ? { attempt: state.attempt } : {}), ...(transport ? { transport } : {}) };
@@ -330,6 +343,14 @@ function diagnoseTunnel(home, node, state = null) {
       detail: `connessione SSH in retry${Number.isInteger(current.attempt) ? ` (tentativo ${current.attempt + 1})` : ''}`,
       hint: 'usa Test connessione per vedere la causa; verifica target SSH, chiave e porta' };
   }
+  if (current.reason === 'degraded' || current.phase === 'degraded') {
+    return {
+      stage: 'ssh', code: current.code || 'reverse-forward-failed', status: 'down', phase: 'degraded',
+      detail: current.detail || 'canale inverso non disponibile, retry fisso in corso',
+      hint: current.hint || 'il tunnel resta attivo e riprovera automaticamente; verifica il listener reverse sul hub',
+      ...(Number.isInteger(current.reversePort) ? { reversePort: current.reversePort } : {}),
+    };
+  }
   if (current.reason === 'failed' || current.phase === 'failed') {
     return {
       stage: 'ssh', code: current.code || 'ssh-terminal-failure', status: 'down', phase: 'failed',

package/lib/proxy/federation.js

@@ -10,6 +10,7 @@ const { safeEqual } = require('../nodes/peering.js');
 const {
   sanitizeRequestHeaders, sanitizeResponseHeaders, stripLocalTokenQuery,
 } = require('./node-proxy.js');
+const { signHop, HOP_HEADER } = require('./hop-proof.js');
 
 const MAX_HOPS = 4;
 const ROUTE_DELIMITER = '_';
@@ -71,6 +72,10 @@ function knownResource(resource) {
     // Hydra: the rest of /settings stays unreachable.
     || resource === '/settings/peering/invite'
     || resource === '/ws'
+    || resource === '/audio/capability'
+    || resource === '/audio/speak'
+    || resource === '/audio/speak/status'
+    || resource === '/audio/stop'
     || /^\/fleet\/(status|schema|definitions|credentials\/status|credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource);
 }
 
@@ -97,9 +102,25 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/ws') return method === 'GET';
   if (/^\/fleet\/(status|schema|definitions|credentials\/status)$/.test(resource)) return method === 'GET';
   if (/^\/fleet\/(credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource)) return method === 'POST';
+  // Audio: only capability read, speak and stop are exposed through Hydra.
+  // audio.consent is a LOCAL mutation and MUST stay unreachable federated.
+  if (resource === '/audio/capability') return method === 'GET';
+  if (resource === '/audio/speak') return method === 'POST';
+  if (resource === '/audio/speak/status') return method === 'POST';
+  if (resource === '/audio/stop') return method === 'POST';
   return false;
 }
 
+// READONLY blocca ogni mutazione che crea o modifica stato, con due eccezioni
+// audio deliberate: interrogare lo status federato usa POST soltanto per
+// trasportare l'attestazione della cella, e Stop e' un'azione di sicurezza che
+// deve poter zittire un endpoint anche quando quel nodo e' READONLY. Speak
+// resta naturalmente bloccato.
+function readonlyBlocksFederated(resource, method) {
+  if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) return false;
+  return resource !== '/audio/speak/status' && resource !== '/audio/stop';
+}
+
 function allowedQuery(resource, method, rawUrl) {
   if (!resource.startsWith('/diagnostics/')) return true;
   const index = String(rawUrl || '').indexOf('?');
@@ -117,17 +138,20 @@ function allowedQuery(resource, method, rawUrl) {
   return true;
 }
 
-function cleanHeaders(headers, credential, visited = null) {
+function cleanHeaders(headers, credential, visited = null, hopProof = null) {
   const out = sanitizeRequestHeaders(headers, credential);
   for (const key of Object.keys(out)) {
     if (['x-nexuscrew-route', 'x-nexuscrew-visited', 'x-nexuscrew-hop'].includes(key.toLowerCase())) delete out[key];
   }
   if (Array.isArray(visited) && visited.length) out['x-nexuscrew-visited'] = visited.join(',');
+  // La prova di hop viene aggiunta DOPO la cancellazione: il canale e' riservato
+  // al server, un valore arrivato dal client non sopravvive mai fin qui.
+  if (hopProof) out[HOP_HEADER] = hopProof;
   return out;
 }
 
-function proxyHttp(req, res, { port, path, credential, visited = null }) {
-  const up = http.request({ host: '127.0.0.1', port, method: req.method, path, headers: cleanHeaders(req.headers, credential, visited) }, (r) => {
+function proxyHttp(req, res, { port, path, credential, visited = null, hopProof = null }) {
+  const up = http.request({ host: '127.0.0.1', port, method: req.method, path, headers: cleanHeaders(req.headers, credential, visited, hopProof) }, (r) => {
     res.writeHead(r.statusCode, sanitizeResponseHeaders(r.headers)); r.pipe(res);
   });
   up.setTimeout(30000, () => up.destroy());
@@ -135,22 +159,28 @@ function proxyHttp(req, res, { port, path, credential, visited = null }) {
   req.pipe(up);
 }
 
-function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false }) {
+function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false, hopSecret = null }) {
   return (req, res) => {
     const parsed = parseRoute(req.url);
     if (!parsed || !allowedResource(parsed.resource, req.method)
       || !allowedQuery(parsed.resource, req.method, req.url)) return res.status(404).json({ error: 'not found' });
-    if (readonly() && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) return res.status(403).json({ error: 'READONLY: federated mutation blocked' });
+    if (readonly() && readonlyBlocksFederated(parsed.resource, req.method)) return res.status(403).json({ error: 'READONLY: federated mutation blocked' });
     const st = store.loadStore(nodesPath);
     if (!st) return res.status(503).json({ error: 'node store unavailable' });
     const visited = controlledVisited(req, ingress, st.nodeId);
     if (!visited) return res.status(409).json({ error: 'federation cycle rejected' });
     if (parsed.route.length === 0) {
+      // Ultimo hop: la richiesta rientra nell'API locale con il Bearer locale e
+      // da li' in poi sarebbe indistinguibile da un POST diretto. La prova di
+      // hop e' cio' che la distingue, ed e' legata a metodo, path e catena.
+      const path = `/api${parsed.resource}${queryOf(req.url)}`;
+      const secret = typeof hopSecret === 'function' ? hopSecret() : hopSecret;
       return proxyHttp(req, res, {
         port: typeof localPort === 'function' ? localPort() : localPort,
-        path: `/api${parsed.resource}${queryOf(req.url)}`,
+        path,
         credential: localCredential(),
         visited,
+        hopProof: signHop(secret, { method: req.method, path, visited }),
       });
     }
     const next = st && store.getNode(st, parsed.route[0]);
@@ -514,7 +544,7 @@ async function collectLocalTopology({
   return { instanceId: live.instanceId, nodes };
 }
 
-function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly = () => false, version = null, roles = null }) {
+function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly = () => false, version = null, roles = null, hopSecret = null }) {
   const r = express.Router();
   r.use((req, res, next) => {
     const peer = peerFromToken(nodesPath, bearerFrom(req));
@@ -576,13 +606,13 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
       return res.status(e.status || 500).json({ error: String(e && e.message || e), ...(e.code ? { code: e.code } : {}) });
     }
   });
-  r.use('/route', (req, res) => routeHandler({ nodesPath, localPort, localCredential, ingress: req.peer, readonly })(req, res));
+  r.use('/route', (req, res) => routeHandler({ nodesPath, localPort, localCredential, ingress: req.peer, readonly, hopSecret })(req, res));
   return r;
 }
 
-function localRouter({ nodesPath, localPort, localCredential, readonly }) {
+function localRouter({ nodesPath, localPort, localCredential, readonly, hopSecret = null }) {
   const r = express.Router();
-  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly })(req, res));
+  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly, hopSecret })(req, res));
   return r;
 }
 
@@ -624,7 +654,7 @@ function reject(socket, code) { try { socket.end(`HTTP/1.1 ${code} Error\r\nConn
 
 module.exports = {
   MAX_HOPS, ROUTE_DELIMITER, TOPOLOGY_PEER_TIMEOUT_MS,
-  peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource, allowedQuery,
+  peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource, allowedQuery, readonlyBlocksFederated,
   collectTopology, collectTopologyDetailed, collectLocalTopology, peerRouter, localRouter, forwardUpgrade,
   probeHealth, waitForHealthyPeer, notifyHubShare, reconcilePeerShare, runShareRevokeBoot,
 };