@mmmbuto/nexuscrew 0.8.26 → 0.8.28

package/lib/fleet/launch.js

@@ -22,6 +22,7 @@ const os = require('node:os');
 const path = require('node:path');
 const { execFile } = require('node:child_process');
 const { minimalRuntimeEnv } = require('../runtime/env.js');
+const { codeOf, phaseOf } = require('./causes.js');
 
 // Env minimale controllato dal service (design §9a). Allowlist DURA: le definizioni
 // non possono toccare PATH/loader-key (parseDefinitions le rifiuta gia' in env);
@@ -34,7 +35,24 @@ function minimalEnv() {
   return minimalRuntimeEnv(process.env, { home: os.homedir() });
 }
 
-function httpError(status, msg, data = null) { const e = new Error(msg); e.status = status; if (data) e.data = data; return e; }
+// httpError(status, msg, data?, cause?) — structured HTTP error. `data` carries
+// arbitrary API detail for the response body; `cause` (T4) is the OPTIONAL
+// bounded failure triple {phase, code} of the up() boundary that failed. The
+// cause is coerced through the closed enum in causes.js (anything not
+// allowlisted degrades to UNKNOWN) and attached as e.fleetCode / e.fleetPhase,
+// so the fleet router can surface {status, code, phase} WITHOUT ever embedding
+// cwd/path, argv, env, prompt, token or credentials. The two channels are kept
+// distinct: `data` is free API detail, `cause` is the bounded failure triple.
+function httpError(status, msg, data = null, cause = null) {
+  const e = new Error(msg);
+  e.status = status;
+  if (data) e.data = data;
+  if (cause) {
+    e.fleetCode = codeOf(cause.code);
+    e.fleetPhase = phaseOf(cause.phase);
+  }
+  return e;
+}
 
 // Marcatore di redazione (design §9h): stderr/stdout dei comandi tmux falliti
 // NON devono mai ecoare i segreti delle definizioni.

package/lib/fleet/managed.js

@@ -7,6 +7,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { execFile } = require('node:child_process');
 const { ENV_KEY_RE } = require('./env-key.js');
+const { termuxRuntimePaths } = require('../runtime/env.js');
 const { readCredentialStore, safePrivateDir } = require('./credentials.js');
 
 const OLLAMA_CLOUD_MODELS = Object.freeze([
@@ -60,7 +61,7 @@ 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 CLIENT_LABELS = Object.freeze({ claude: 'Claude Code', codex: 'Codex', 'codex-vl': 'Codex-VL', pi: 'Pi' });
+const CLIENT_LABELS = Object.freeze({ claude: 'Claude Code', codex: 'Codex', 'codex-vl': 'Codex-VL', pi: 'Pi', shell: 'Shell' });
 const PROVIDER_ID_RE = /^[a-z][a-z0-9_-]{0,31}$/;
 
 function validBaseUrl(value) {
@@ -108,6 +109,9 @@ const CATALOG = Object.freeze([
   // Pi uses its real provider IDs directly. OAuth providers do not need env keys.
   { id: 'pi.native', client: 'pi', provider: 'native', label: 'Pi configured default', auth: 'login', protocol: 'pi_native', default: true, core: true },
   { id: 'pi.alibaba-token-plan', client: 'pi', provider: 'alibaba-token-plan', label: 'Alibaba Token Plan Personal', auth: 'ALIBABA_CODE_API_KEY', endpoint: 'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1', protocol: 'openai-completions', model: 'qwen3.8-max-preview', models: ALIBABA_TOKEN_PLAN_MODELS, strictModels: true, piProvider: 'alibaba-token-plan', piExtension: { baseUrl: 'https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1', models: ALIBABA_PI_MODELS }, delegatePiAuth: false, core: true, notice: 'alibaba-token-plan' },
+  // Device-local shell. Kept after the established default clients so adding
+  // it does not change the preselected engine for a newly-created cell.
+  { id: 'shell.local', client: 'shell', provider: 'local', label: 'Shell', auth: 'none', protocol: 'shell', default: true, core: true },
   { id: 'pi.anthropic', client: 'pi', provider: 'anthropic', label: 'Anthropic', auth: 'ANTHROPIC_API_KEY', protocol: 'pi_native', piProvider: 'anthropic', core: true },
   { id: 'pi.openai', client: 'pi', provider: 'openai', label: 'OpenAI API', auth: 'OPENAI_API_KEY', protocol: 'pi_native', piProvider: 'openai', core: true },
   { id: 'pi.openai-codex', client: 'pi', provider: 'openai-codex', label: 'OpenAI Codex OAuth', auth: 'login', protocol: 'pi_native', piProvider: 'openai-codex', core: true },
@@ -147,11 +151,12 @@ function normalizeManagedSpec(value) {
   if (!profile) return null;
   const model = value.model === undefined ? (profile.model || '') : value.model;
   if (typeof model !== 'string' || model.length > 128 || /[\x00-\x1f\x7f]/.test(model)) return null;
+  if (value.client === 'shell' && model) return null;
   if (profile.requiresModel && !model) return null;
   if (profile.strictModels && !(profile.models || []).includes(model)) return null;
   const permissionPolicy = value.permissionPolicy === undefined ? (profile.client === 'claude' ? 'unsafe' : 'standard') : value.permissionPolicy;
   if (permissionPolicy !== 'standard' && permissionPolicy !== 'unsafe') return null;
-  if (value.client === 'pi' && permissionPolicy !== 'standard') return null;
+  if ((value.client === 'pi' || value.client === 'shell') && permissionPolicy !== 'standard') return null;
   const out = { client: profile.client, provider: profile.provider, model, permissionPolicy };
   if (profile.credentialProfile) out.credentialProfile = profile.credentialProfile;
   if (profile.credentialEnv) {
@@ -187,6 +192,16 @@ function defaultDefinitions() {
   };
 }
 
+function defaultShellEngine() {
+  const profile = CATALOG.find((entry) => entry.id === 'shell.local');
+  return {
+    id: profile.id,
+    label: CLIENT_LABELS.shell,
+    rc: false,
+    managed: { client: 'shell', provider: 'local', model: '', permissionPolicy: 'standard' },
+  };
+}
+
 function parseAssignments(raw) {
   const out = {};
   for (const line of raw.split(/\r?\n/)) {
@@ -268,14 +283,50 @@ function findBinary(client, home) {
   return null;
 }
 
+// Resolve a device-local interactive shell without persisting a path in
+// fleet.json. Candidates are ordered and fail closed. Symlinks are resolved
+// first, then the existing command trust policy is applied to the real file.
+function resolveInteractiveShell(cfg = {}) {
+  const env = cfg.env || process.env;
+  const platform = cfg.platform || process.platform;
+  const termux = termuxRuntimePaths(env, { platform, home: cfg.home });
+  const candidates = [];
+  if (typeof env.SHELL === 'string' && path.isAbsolute(env.SHELL)) candidates.push(env.SHELL);
+  if (termux?.prefix) {
+    candidates.push(path.join(termux.prefix, 'bin', 'bash'));
+    candidates.push(path.join(termux.prefix, 'bin', 'sh'));
+  }
+  candidates.push('/bin/bash', '/bin/sh');
+  const validate = cfg.validateCommandTrust
+    || ((command) => require('./definitions.js').validateCommandTrust(command));
+  for (const candidate of [...new Set(candidates)]) {
+    try {
+      const real = fs.realpathSync(candidate);
+      if (validate(real).ok) return real;
+    } catch (_) { /* next candidate */ }
+  }
+  return null;
+}
+
+function shellLoginArgs(command) {
+  return ['bash', 'zsh', 'sh', 'dash'].includes(path.basename(String(command || ''))) ? ['-l'] : [];
+}
+
 // Termux reports process.platform === 'android' and deliberately has no
 // /usr/bin/env.  npm CLI shims commonly resolve to a JavaScript file with
 // `#!/usr/bin/env node`; direct tmux exec then fails in the kernel before the
 // client starts.  Detect only that explicit Node shebang and invoke it through
 // the already-running trusted Node executable.  Native and shell binaries keep
 // their original direct-exec path.
-function needsExplicitNode(binary, platform = process.platform) {
-  if (platform !== 'android') return false;
+//
+// Detection uses both process.platform AND the runtime Termux layout (PREFIX /
+// files/home) so that a Node build that reports `linux` while actually running
+// under Termux (proot / custom build) still gets the shebang workaround. The
+// optional `env` argument lets tests inject a synthetic environment; the public
+// two-argument call form is unchanged.
+function needsExplicitNode(binary, platform = process.platform, env = process.env) {
+  const termux = platform === 'android' || termuxRuntimePaths(env, { platform }) !== null;
+  if (!termux) return false;
   try {
     const fd = fs.openSync(binary, 'r');
     try {
@@ -414,7 +465,9 @@ function describeManaged(spec, cfg = {}) {
   if (!normalized) return { configured: false, reason: 'invalid managed profile' };
   const home = cfg.home || require('node:os').homedir();
   const profile = profileFor(normalized.client, normalized.provider, normalized.credentialProfile || '');
-  const binary = findBinary(normalized.client, home);
+  const binary = normalized.client === 'shell'
+    ? resolveInteractiveShell({ ...cfg, home })
+    : findBinary(normalized.client, home);
   const cred = credential(profile, normalized, cfg, home);
   // Pi can resolve credentials from its own documented /login auth store. Do
   // not inspect or copy that store; delegate native-provider auth to Pi.
@@ -577,13 +630,20 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
   let effectivePolicy = (override === 'standard' || override === 'unsafe') ? override : spec.permissionPolicy;
   // Pi resta sempre 'standard': normalizeManagedSpec rifiuta gia' unsafe nello spec
   // dell'engine, ma l'override PER-CELL bypasserebbe quel check -> clamp esplicito.
-  if (spec.client === 'pi') effectivePolicy = 'standard';
+  if (spec.client === 'pi' || spec.client === 'shell') effectivePolicy = 'standard';
   info.permissionPolicy = effectivePolicy;
   if (effectivePolicy === 'unsafe') {
     if (spec.client === 'claude') args.push('--dangerously-skip-permissions');
     if (spec.client === 'codex' || spec.client === 'codex-vl') args.push('--dangerously-bypass-approvals-and-sandbox');
   }
-  if (spec.client === 'claude') {
+  let shellOneShot = false;
+  if (spec.client === 'shell') {
+    const raw = cell?.commands && typeof cell.commands[engineId] === 'string'
+      ? cell.commands[engineId] : '';
+    shellOneShot = raw.trim().length > 0;
+    if (shellOneShot) args.push('-lc', raw);
+    else args.push(...shellLoginArgs(info.binary));
+  } else if (spec.client === 'claude') {
     if (spec.provider === 'native') {
       if (engine.rc !== false) args.push('--remote-control', `Cloud_${cell.id}`);
     } else if (profile.providerEnv) {
@@ -700,14 +760,15 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     if (model) args.push('--model', model);
     if (spec.provider === 'alibaba-token-plan' && model === 'qwen3.8-max-preview') args.push('--thinking', 'xhigh');
   }
-  if (cell?.prompt) args.push(cell.prompt);
+  if (spec.client !== 'shell' && cell?.prompt) args.push(cell.prompt);
   let command = info.binary;
-  if (needsExplicitNode(info.binary, cfg.platform || process.platform)) {
+  if (needsExplicitNode(info.binary, cfg.platform || process.platform, cfg.env || process.env)) {
     command = cfg.nodeExecPath || process.execPath;
     args.unshift(info.binary);
   }
   return { ok: true, info, engine: {
     ...engine, command, args, env, promptMode: 'managed-argv', clientBinary: info.binary,
+    ...(spec.client === 'shell' ? { shellOneShot } : {}),
   } };
 }
 
@@ -716,7 +777,7 @@ function publicCatalog() {
     id: p.id, client: p.client, clientLabel: CLIENT_LABELS[p.client], provider: p.provider,
     credentialProfile: p.credentialProfile || '', label: p.label, protocol: p.protocol,
     auth: p.auth, endpoint: p.endpoint || '', model: p.model || '', models: [...(p.models || [])],
-    protocols: [...(p.protocols || [p.protocol])], supportsUnsafe: p.client !== 'pi', requiresModel: !!p.requiresModel || !!p.custom,
+    protocols: [...(p.protocols || [p.protocol])], supportsUnsafe: !['pi', 'shell'].includes(p.client), requiresModel: !!p.requiresModel || !!p.custom,
     permissionPolicyDefault: p.client === 'claude' ? 'unsafe' : 'standard',
     rc: !!p.rc, custom: !!p.custom, default: !!p.default, notice: p.notice || '',
     credentialEnv: p.auth === 'dynamic' ? !!p.credentialEnv : (ENV_KEY_RE.test(p.auth || '') ? p.auth : false),
@@ -728,8 +789,8 @@ 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,
-  defaultDefinitions, describeManaged, describeCatalogCredential, discoverOllamaModels, resolveManagedEngine, needsExplicitNode,
+  defaultDefinitions, defaultShellEngine, describeManaged, describeCatalogCredential, discoverOllamaModels, resolveManagedEngine, needsExplicitNode,
   discoverPiModels, parseEnvFile, parseProviderShellFile, findBinary, publicCatalog, writePiProviderExtension,
   providerKeyPaths, parseProviderKeyFiles, credentialSources, credential,
-  ensureKimiClaudeConfig, ensureAlibabaClaudeConfig, ENV_KEY_RE,
+  ensureKimiClaudeConfig, ensureAlibabaClaudeConfig, resolveInteractiveShell, shellLoginArgs, ENV_KEY_RE,
 };

package/lib/fleet/routes.js

@@ -1,5 +1,6 @@
 'use strict';
 const express = require('express');
+const { codeOf, phaseOf } = require('./causes.js');
 
 // Fallback difensivo per un adapter builtin incompleto nei test. Il provider di
 // prodotto dichiara sempre la propria capability list.
@@ -29,6 +30,14 @@ function fleetRoutes(fleetP, cfg = {}) {
   r.use((req, res, next) => (req.path === '/restore-cells' || req.path === '/restore-engines' ? restoreJson : smallJson)(req, res, next));
 
   const readonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
+  const diagnostics = cfg.diagnostics || null;
+  const safeCell = (body) => {
+    const value = body && typeof body.cell === 'string' ? body.cell : '';
+    return /^[A-Za-z0-9._-]{1,32}$/.test(value) ? value : '';
+  };
+  const emit = (level, code, message, meta) => {
+    if (diagnostics && typeof diagnostics.record === 'function') diagnostics.record(level, 'fleet', code, message, meta);
+  };
 
   const guard = (fn, opts = {}) => async (req, res) => {
     try {
@@ -36,9 +45,39 @@ function fleetRoutes(fleetP, cfg = {}) {
       if (opts.mutate && readonly()) return res.status(403).json({ error: 'READONLY: mutazione fleet bloccata' });
       const fleet = await fleetP;
       if (!fleet.available) return res.status(404).json({ error: 'fleet non disponibile' });
-      res.json(await fn(fleet, req.body || {}));
+      const body = req.body || {};
+      if (opts.action) emit('info', 'FLEET_ACTION_STARTED', 'Fleet action started', {
+        action: opts.action, cell: safeCell(body), state: 'starting',
+      });
+      const result = await fn(fleet, body);
+      if (opts.action) emit('info', 'FLEET_ACTION_COMPLETED', 'Fleet action completed', {
+        action: opts.action, cell: safeCell(body), state: opts.action === 'down' ? 'stopped' : 'ready',
+      });
+      res.json(result);
     } catch (e) {
-      res.status(e.status || 500).json({ error: String(e.message || e), ...(e.data || {}) });
+      if (opts.action) {
+        const match = String(e && e.message || '').match(/cell spawn failed:\s+([A-Z][A-Z0-9_]{0,31})\s+([A-Za-z0-9._+-]{1,128})/);
+        if (match) emit('error', 'CELL_SPAWN_FAILED', 'Cell client spawn failed', {
+          action: opts.action, cell: safeCell(req.body), errno: match[1], client: match[2], status: e.status || 500,
+        });
+        else emit('warn', 'FLEET_ACTION_FAILED', 'Fleet action failed', {
+          action: opts.action, cell: safeCell(req.body), state: 'failed',
+          status: e.status || 500,
+          // Cause-preserving (T4): bounded enum only (lib/fleet/causes.js). The
+          // cause triple is {status, code, phase}; no free message, cwd/path,
+          // argv, env, prompt, token or credential ever enters here. Untagged /
+          // legacy errors degrade to the bounded UNKNOWN fallback.
+          code: codeOf(e.fleetCode), phase: phaseOf(e.fleetPhase),
+        });
+      }
+      res.status(e.status || 500).json({
+        error: String(e.message || e),
+        ...(e.data || {}),
+        // Structured, bounded cause on the HTTP error too: stable enum only,
+        // never cwd/path, argv, env, prompt, token or credentials. Untagged
+        // errors (no fleetCode) keep the historical response shape.
+        ...(e.fleetCode ? { code: codeOf(e.fleetCode), phase: phaseOf(e.fleetPhase) } : {}),
+      });
     }
   };
 
@@ -82,13 +121,13 @@ function fleetRoutes(fleetP, cfg = {}) {
       await f.boot(cell, b.boot === true);
     }
     return f.up(cell, { engine: b.engine, boot: !!b.boot });
-  }, { mutate: true }));
+  }, { mutate: true, action: 'up' }));
   r.post('/down', guard(async (f, b) => {
     const cell = String(b.cell || '');
     if (b.boot === true && capList(f).includes('edit') && capList(f).includes('boot')) await f.boot(cell, false);
     return f.down(cell, { boot: !!b.boot });
-  }, { mutate: true }));
-  r.post('/restart', guard((f, b) => { requireCap(f, 'restart'); return f.restart(String(b.cell || '')); }, { mutate: true }));
+  }, { mutate: true, action: 'down' }));
+  r.post('/restart', guard((f, b) => { requireCap(f, 'restart'); return f.restart(String(b.cell || '')); }, { mutate: true, action: 'restart' }));
   r.post('/engine', guard((f, b) => {
     const opts = { model: typeof b.model === 'string' ? b.model : '' };
     if (typeof b.permissionPolicy === 'string') opts.permissionPolicy = b.permissionPolicy;

package/lib/fleet/runtime.js

@@ -85,7 +85,7 @@ function createBuiltinRuntime(ctx) {
       const remembered = c.permissionPolicies
         && (c.permissionPolicies[c.engine] === 'standard' || c.permissionPolicies[c.engine] === 'unsafe')
         ? c.permissionPolicies[c.engine] : null;
-      const effectivePolicy = engineDef?.managed?.client === 'pi'
+      const effectivePolicy = ['pi', 'shell'].includes(engineDef?.managed?.client)
         ? 'standard'
         : (remembered || engineDefault || '');
       return {
@@ -149,16 +149,19 @@ function createBuiltinRuntime(ctx) {
     let launchEngine = engine;
     if (engine.managed) {
       const resolved = resolveManagedEngine(engine, cell, { ...cfg, home });
-      if (!resolved.ok) throw httpError(400, `engine managed non configurato (${engine.id}): ${resolved.reason}`);
+      if (!resolved.ok) {
+        const code = engine.managed.client === 'shell' ? 'SHELL_NOT_AVAILABLE' : 'ENGINE_UNCONFIGURED';
+        throw httpError(400, `engine managed non configurato (${engine.id}): ${resolved.reason}`, null, { phase: 'preflight', code });
+      }
       launchEngine = resolved.engine;
     }
 
     // (2) trust del command PRIMA di lanciare
     const trust = validateCommandTrust(launchEngine.command);
-    if (!trust.ok) throw httpError(400, `command non trusted (${launchEngine.command}): ${trust.reason}`);
+    if (!trust.ok) throw httpError(400, `command non trusted (${launchEngine.command}): ${trust.reason}`, null, { phase: 'preflight', code: 'COMMAND_UNTRUSTED' });
     // (3) cwd reale sotto la home
     const realCwd = resolveCwd(cell.cwd, home);
-    if (!realCwd) throw httpError(400, `cwd non valida (deve esistere sotto la home): ${cell.cwd}`);
+    if (!realCwd) throw httpError(400, `cwd non valida (deve esistere sotto la home): ${cell.cwd}`, null, { phase: 'preflight', code: 'CWD_INVALID' });
 
     // (4)+(5) argv diretto (no shell). Every cell goes through the private
     // broker-backed supervisor: credentials never enter tmux state/argv and a
@@ -168,32 +171,46 @@ function createBuiltinRuntime(ctx) {
     // #5: elimina la race di riuso del nome sessione tra waitAlive e paste).
     const readyMs = cfg.launchReadyMs != null ? cfg.launchReadyMs : 500;
     const child = composeClientInvocation(launchEngine, cell);
-    const ticket = await launchBroker.issue({
-      command: child.command,
-      args: child.args,
-      env: {
-        ...minimalEnv(),
-        ...launchEngine.env,
-        NEXUSCREW_MCP_SESSION: cell.tmuxSession,
-      },
-      supervise: {
-        enabled: true,
-        initialReadyMs: Math.max(50, Math.min(30000, Number(readyMs) || 500)),
-        restartDelayMs: Math.max(50, Math.min(60000, Number(cfg.cellRestartDelayMs) || 1000)),
-        maxRestartDelayMs: Math.max(100, Math.min(300000, Number(cfg.cellMaxRestartDelayMs) || 60000)),
-        resetAfterMs: Math.max(1000, Math.min(3600000, Number(cfg.cellRestartResetMs) || 30000)),
-        rapidWindowMs: Math.max(1000, Math.min(3600000, Number(cfg.cellRapidWindowMs) || 60000)),
-        maxRapidRestarts: Math.max(1, Math.min(100, Number(cfg.cellMaxRapidRestarts) || 8)),
-      },
-      ...(launchEngine.promptMode === 'send-keys' && cell.prompt ? {
-        restartPrompt: {
-          tmuxBin,
-          tmuxSession: cell.tmuxSession,
-          prompt: cell.prompt,
-          readyMs: Math.max(0, Math.min(30000, Number(cfg.sendKeysReadyMs) || readyMs)),
+    let ticket;
+    try {
+      ticket = await launchBroker.issue({
+        command: child.command,
+        args: child.args,
+        env: {
+          ...minimalEnv(),
+          ...launchEngine.env,
+          NEXUSCREW_MCP_SESSION: cell.tmuxSession,
         },
-      } : {}),
-    });
+        supervise: {
+          enabled: !launchEngine.shellOneShot,
+          initialReadyMs: Math.max(50, Math.min(30000, Number(readyMs) || 500)),
+          restartDelayMs: Math.max(50, Math.min(60000, Number(cfg.cellRestartDelayMs) || 1000)),
+          maxRestartDelayMs: Math.max(100, Math.min(300000, Number(cfg.cellMaxRestartDelayMs) || 60000)),
+          resetAfterMs: Math.max(1000, Math.min(3600000, Number(cfg.cellRestartResetMs) || 30000)),
+          rapidWindowMs: Math.max(1000, Math.min(3600000, Number(cfg.cellRapidWindowMs) || 60000)),
+          maxRapidRestarts: Math.max(1, Math.min(100, Number(cfg.cellMaxRapidRestarts) || 8)),
+        },
+        ...(launchEngine.promptMode === 'send-keys' && cell.prompt ? {
+          restartPrompt: {
+            tmuxBin,
+            tmuxSession: cell.tmuxSession,
+            prompt: cell.prompt,
+            readyMs: Math.max(0, Math.min(30000, Number(cfg.sendKeysReadyMs) || readyMs)),
+          },
+        } : {}),
+      });
+    } catch (brokerErr) {
+      const bmsg = String((brokerErr && brokerErr.message) || brokerErr);
+      const bcode = /too large/i.test(bmsg) ? 'LAUNCH_BROKER_PAYLOAD'
+        : /closed/i.test(bmsg) ? 'LAUNCH_BROKER_CLOSED'
+        : /unsafe launch broker/i.test(bmsg) ? 'LAUNCH_BROKER_UNSAFE'
+        : 'LAUNCH_BROKER_FAILED';
+      const bpublic = bcode === 'LAUNCH_BROKER_PAYLOAD' ? 'launch broker payload rifiutato'
+        : bcode === 'LAUNCH_BROKER_CLOSED' ? 'launch broker non disponibile'
+        : bcode === 'LAUNCH_BROKER_UNSAFE' ? 'launch broker non sicuro'
+        : 'launch broker failed';
+      throw httpError(500, bpublic, null, { phase: 'launch-broker', code: bcode });
+    }
     const tmuxLaunchEngine = {
       command: process.execPath,
       args: [path.join(__dirname, 'cell-exec.js'), '--socket', ticket.socketPath, '--nonce', ticket.nonce],
@@ -204,14 +221,27 @@ function createBuiltinRuntime(ctx) {
     // Mantieni il pane morto solo durante la finestra di readiness: permette di
     // catturare un errore reale del client senza lasciare una sessione fantasma.
     // Il separatore e' interpretato da tmux (execFile argv diretto), non da shell.
-    argv.push(';', 'set-option', '-w', '-t', `=${cell.tmuxSession}:`, 'remain-on-exit', 'on');
+    if (!launchEngine.shellOneShot) {
+      argv.push(';', 'set-option', '-w', '-t', `=${cell.tmuxSession}:`, 'remain-on-exit', 'on');
+    }
     const launch = await tmuxExec(tmuxBin, argv, { env: minimalEnv() });
     if (launch.err) {
       // Redazione (§9h): lo stderr di tmux puo' ecoare argv/env del comando lanciato.
-      const why = /duplicate session/i.test(launch.stderr)
+      const dup = /duplicate session/i.test(launch.stderr);
+      const why = dup
         ? 'sessione già in esecuzione'
         : `tmux new-session failed: ${redactSecrets(launch.stderr.trim() || launch.err.message, launchEngine, cell)}`;
-      throw httpError(/duplicate/i.test(launch.stderr) ? 409 : 500, why);
+      throw httpError(dup ? 409 : 500, why, null,
+        { phase: 'new-session', code: dup ? 'SESSION_DUPLICATE' : 'NEW_SESSION_FAILED' });
+    }
+
+    // Un comando Shell valorizzato e' intenzionalmente one-shot: l'uscita del
+    // processo, anche immediata o non-zero, e' il risultato del comando e non
+    // un crash del client Fleet. Non si mantiene il pane e non si abilita il
+    // supervisore; la cella torna inattiva quando la shell termina.
+    if (launchEngine.shellOneShot) {
+      cache = { ...cache, at: 0 };
+      return { ok: true, cell: cellId, session: cell.tmuxSession, prompt: null, oneShot: true };
     }
 
     // `tmux new-session -d` can return 0 even when the launched CLI exits a
@@ -235,7 +265,13 @@ function createBuiltinRuntime(ctx) {
       cache = { ...cache, at: 0 };
       const client = path.basename(launchEngine.clientBinary || launchEngine.command || 'client');
       const status = Number.isInteger(readiness.status) ? ` (exit ${readiness.status})` : '';
-      throw httpError(500, `client ${client} terminato subito${status}: ${diagnostic || 'verifica login, provider, modello e argomenti dell\'engine'}`);
+      // Cause-preserving (T4): distinguish a cell-client spawn failure (the
+      // captured pane carries the stable 'cell spawn failed:' marker produced by
+      // cell-exec.js) from a generic early exit. Both stay on the readiness
+      // surface; the spawn branch keeps CELL_SPAWN_FAILED sanitized downstream.
+      const isSpawn = /cell spawn failed:/.test(diagnostic);
+      throw httpError(500, `client ${client} terminato subito${status}: ${diagnostic || 'verifica login, provider, modello e argomenti dell\'engine'}`, null,
+        isSpawn ? { phase: 'spawn-client', code: 'SPAWN_CLIENT_FAILED' } : { phase: 'readiness', code: 'CLIENT_EARLY_EXIT' });
     }
     if (readiness.target) {
       await tmuxExec(tmuxBin,

package/lib/nodes/aliases.js

@@ -0,0 +1,122 @@
+'use strict';
+// Alias locali del viewer per nodi routed. Questo store non partecipa mai a
+// topology, routing, ACL o federation: associa soltanto uno stable instanceId a
+// un'etichetta di display scelta sul dispositivo che ospita la PWA.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const SCHEMA_VERSION = 1;
+const INSTANCE_ID_RE = /^[a-f0-9]{16,64}$/;
+const ALIAS_MAX = 64;
+const MAX_ALIASES = 128;
+const MAX_FILE_BYTES = 16 * 1024;
+
+function defaultAliasesPath(home = os.homedir()) {
+  return path.join(home, '.nexuscrew', 'node-aliases.json');
+}
+
+function normalizeAlias(value) {
+  if (typeof value !== 'string') return null;
+  const alias = value.normalize('NFC').trim();
+  if (!alias || alias.length > ALIAS_MAX) return null;
+  // Cc/Cf includes newlines, NUL, bidi controls and invisible format chars.
+  if (/[\p{Cc}\p{Cf}]/u.test(alias)) return null;
+  return alias;
+}
+
+function emptyStore() {
+  return { version: SCHEMA_VERSION, aliasesByInstanceId: {} };
+}
+
+function parseStore(raw) {
+  let value;
+  try { value = typeof raw === 'string' ? JSON.parse(raw) : raw; } catch (_) { return null; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  if (Object.keys(value).some((key) => !['version', 'aliasesByInstanceId'].includes(key))) return null;
+  if (value.version !== SCHEMA_VERSION) return null;
+  const aliases = value.aliasesByInstanceId;
+  if (!aliases || typeof aliases !== 'object' || Array.isArray(aliases)) return null;
+  const entries = Object.entries(aliases);
+  if (entries.length > MAX_ALIASES) return null;
+  const out = {};
+  for (const [instanceId, rawAlias] of entries) {
+    const alias = normalizeAlias(rawAlias);
+    if (!INSTANCE_ID_RE.test(instanceId) || alias === null || alias !== rawAlias) return null;
+    out[instanceId] = alias;
+  }
+  return { version: SCHEMA_VERSION, aliasesByInstanceId: out };
+}
+
+function assertSafeTarget(filePath) {
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('node alias store must be a regular file');
+    if ((stat.mode & 0o077) !== 0) throw new Error('node alias store permissions must be 0600');
+    if (stat.size > MAX_FILE_BYTES) throw new Error('node alias store exceeds size limit');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return false;
+    throw error;
+  }
+  return true;
+}
+
+function loadStore(filePath = defaultAliasesPath()) {
+  if (!assertSafeTarget(filePath)) return emptyStore();
+  const raw = fs.readFileSync(filePath, { encoding: 'utf8', flag: 'r' });
+  if (Buffer.byteLength(raw) > MAX_FILE_BYTES) throw new Error('node alias store exceeds size limit');
+  const parsed = parseStore(raw);
+  if (!parsed) throw new Error('invalid node alias store');
+  return parsed;
+}
+
+function atomicWriteStore(filePath, store) {
+  const parsed = parseStore(store);
+  if (!parsed) throw new Error('invalid node alias store');
+  const payload = `${JSON.stringify(parsed, null, 2)}\n`;
+  if (Buffer.byteLength(payload) > MAX_FILE_BYTES) throw new Error('node alias store exceeds size limit');
+  assertSafeTarget(filePath);
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const dirStat = fs.lstatSync(dir);
+  if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) throw new Error('node alias directory must be a regular directory');
+  fs.chmodSync(dir, 0o700);
+  const tmp = path.join(dir, `.${path.basename(filePath)}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, payload, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, filePath);
+    fs.chmodSync(filePath, 0o600);
+  } catch (error) {
+    try { fs.unlinkSync(tmp); } catch (_) { /* best effort */ }
+    throw error;
+  }
+  return parsed;
+}
+
+function setAlias(store, instanceId, value) {
+  if (!INSTANCE_ID_RE.test(String(instanceId || ''))) throw new Error('instanceId non valido');
+  const alias = normalizeAlias(value);
+  if (alias === null) throw new Error('alias non valido (max 64 char, niente controlli)');
+  const current = parseStore(store);
+  if (!current) throw new Error('invalid node alias store');
+  const aliasesByInstanceId = { ...current.aliasesByInstanceId, [instanceId]: alias };
+  if (Object.keys(aliasesByInstanceId).length > MAX_ALIASES) throw new Error('troppi alias nodo');
+  return { version: SCHEMA_VERSION, aliasesByInstanceId };
+}
+
+function deleteAlias(store, instanceId) {
+  if (!INSTANCE_ID_RE.test(String(instanceId || ''))) throw new Error('instanceId non valido');
+  const current = parseStore(store);
+  if (!current) throw new Error('invalid node alias store');
+  const aliasesByInstanceId = { ...current.aliasesByInstanceId };
+  delete aliasesByInstanceId[instanceId];
+  return { version: SCHEMA_VERSION, aliasesByInstanceId };
+}
+
+module.exports = {
+  SCHEMA_VERSION, INSTANCE_ID_RE, ALIAS_MAX, MAX_ALIASES, MAX_FILE_BYTES,
+  defaultAliasesPath, normalizeAlias, emptyStore, parseStore, loadStore,
+  atomicWriteStore, setAlias, deleteAlias,
+};

package/lib/proxy/federation.js

@@ -63,6 +63,9 @@ function knownResource(resource) {
     || resource === '/decks'
     || /^\/decks\/[a-z0-9-]{1,32}$/.test(resource)
     || resource === '/topology'
+    || resource === '/diagnostics/status'
+    || resource === '/diagnostics/logs'
+    || resource === '/diagnostics/verbose'
     // A connected client may ask its hub to mint a hub-owned, one-time
     // pairing invite. This is the only settings mutation exposed through
     // Hydra: the rest of /settings stays unreachable.
@@ -87,6 +90,9 @@ function allowedResource(resource, method = 'GET') {
     return method === 'PUT' || method === 'PATCH' || method === 'DELETE';
   }
   if (resource === '/topology') return method === 'GET';
+  if (resource === '/diagnostics/status') return method === 'GET';
+  if (resource === '/diagnostics/logs') return method === 'GET' || method === 'DELETE';
+  if (resource === '/diagnostics/verbose') return method === 'PATCH';
   if (resource === '/settings/peering/invite') return method === 'POST';
   if (resource === '/ws') return method === 'GET';
   if (/^\/fleet\/(status|schema|definitions|credentials\/status)$/.test(resource)) return method === 'GET';
@@ -94,6 +100,23 @@ function allowedResource(resource, method = 'GET') {
   return false;
 }
 
+function allowedQuery(resource, method, rawUrl) {
+  if (!resource.startsWith('/diagnostics/')) return true;
+  const index = String(rawUrl || '').indexOf('?');
+  if (index < 0) return true;
+  const raw = String(rawUrl).slice(index + 1);
+  if (!raw) return true;
+  if (resource !== '/diagnostics/logs' || method !== 'GET') return false;
+  const params = new URLSearchParams(raw);
+  const keys = [...params.keys()];
+  if (keys.some((key) => !['after', 'limit'].includes(key))) return false;
+  if (params.getAll('after').length > 1 || params.getAll('limit').length > 1) return false;
+  const after = params.get('after'); const limit = params.get('limit');
+  if (after !== null && (!/^\d{1,16}$/.test(after) || !Number.isSafeInteger(Number(after)))) return false;
+  if (limit !== null && (!/^\d{1,3}$/.test(limit) || Number(limit) < 1 || Number(limit) > 200)) return false;
+  return true;
+}
+
 function cleanHeaders(headers, credential, visited = null) {
   const out = sanitizeRequestHeaders(headers, credential);
   for (const key of Object.keys(out)) {
@@ -115,7 +138,8 @@ function proxyHttp(req, res, { port, path, credential, visited = null }) {
 function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false }) {
   return (req, res) => {
     const parsed = parseRoute(req.url);
-    if (!parsed || !allowedResource(parsed.resource, req.method)) return res.status(404).json({ error: 'not found' });
+    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' });
     const st = store.loadStore(nodesPath);
     if (!st) return res.status(503).json({ error: 'node store unavailable' });
@@ -539,7 +563,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,
+  peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource, allowedQuery,
   collectTopology, collectTopologyDetailed, collectLocalTopology, peerRouter, localRouter, forwardUpgrade,
   probeHealth, waitForHealthyPeer, notifyHubShare, reconcilePeerShare,
 };