@mmmbuto/nexuscrew 0.8.29 → 0.8.31

package/lib/fleet/launch.js

@@ -23,6 +23,7 @@ const path = require('node:path');
 const { execFile } = require('node:child_process');
 const { minimalRuntimeEnv } = require('../runtime/env.js');
 const { codeOf, phaseOf } = require('./causes.js');
+const { isTmuxSafeName, tmuxSessionForCell } = require('./definitions.js');
 
 // Env minimale controllato dal service (design §9a). Allowlist DURA: le definizioni
 // non possono toccare PATH/loader-key (parseDefinitions le rifiuta gia' in env);
@@ -129,6 +130,128 @@ function tmuxExec(tmuxBin, args, { env, timeoutMs = 10000 } = {}) {
 
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 
+function tmuxMigrationError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function boundedTmuxFailure(result) {
+  return String(result?.stderr || result?.err?.message || 'errore tmux')
+    .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 240) || 'errore tmux';
+}
+
+// Migrazione identita' tmux (design §3.2). Prima costruisce e valida TUTTO il
+// piano: nessun rename parte se una sessione legacy normalizzata e' rivendicata
+// da piu celle (es. a.b vs a_b), se legacy+target safe coesistono o se il target
+// non e' tmux-safe. Solo dopo il preflight rinomina via `$N`; qualunque errore e'
+// propagato con causa bounded e impedisce la persistenza di fleet.json. I rename
+// gia riusciti prima di un errore operativo restano comunque idempotenti al boot
+// successivo, mentre lo store precedente rimane intatto.
+async function migrateLegacyTmuxSessions(tmuxBin, defs, { readonly = false } = {}) {
+  const cells = defs && Array.isArray(defs.cells) ? defs.cells : [];
+  const legacyMap = defs?.legacyTmuxSessions instanceof Map ? defs.legacyTmuxSessions : new Map();
+  const candidates = [];
+  for (const cell of cells) {
+    if (!cell || typeof cell.id !== 'string') continue;
+    const legacyRaw = legacyMap.get(cell.id) || (cell.id.includes('.') ? `cloud-${cell.id}` : '');
+    if (!legacyRaw) continue;
+    const safe = cell.tmuxSession || tmuxSessionForCell(cell.id);
+    if (!isTmuxSafeName(safe)) {
+      throw tmuxMigrationError('TMUX_MIGRATION_INVALID_TARGET',
+        `migrazione tmux bloccata per ${cell.id}: target safe non valido`);
+    }
+    candidates.push({ id: cell.id, legacyRaw, legacyNorm: legacyRaw.replace(/\./g, '_'), safe });
+  }
+  if (!candidates.length || readonly) {
+    return {
+      migrated: [], reason: readonly ? 'readonly' : 'none',
+      needsPersistence: legacyMap.size > 0,
+    };
+  }
+  const listing = await tmuxExec(tmuxBin,
+    ['list-sessions', '-F', '#{session_id}\t#{session_name}'], { env: minimalEnv() });
+  if (listing.err) {
+    const detail = boundedTmuxFailure(listing);
+    if (/no server running|failed to connect|connection refused|no such file.*tmux/i.test(detail)) {
+      return { migrated: [], reason: 'no-tmux-server', needsPersistence: legacyMap.size > 0 };
+    }
+    throw tmuxMigrationError('TMUX_MIGRATION_LIST_FAILED',
+      `migrazione tmux: elenco sessioni non disponibile (${detail})`);
+  }
+  const realByName = new Map(); // session_name -> session_id ($N)
+  for (const line of listing.stdout.split('\n')) {
+    const [sid, sname] = line.split('\t');
+    if (sid && sname) realByName.set(String(sname).trim(), String(sid).trim());
+  }
+
+  const ownersBySafe = new Map(cells.map((cell) => [cell.tmuxSession, cell.id]));
+  const claimsByReal = new Map();
+  for (const candidate of candidates) {
+    for (const name of new Set([candidate.legacyRaw, candidate.legacyNorm])) {
+      if (!realByName.has(name)) continue;
+      const claims = claimsByReal.get(name) || [];
+      claims.push(candidate);
+      claimsByReal.set(name, claims);
+    }
+  }
+
+  const activeNamesByCell = new Map();
+  for (const [realName, claims] of claimsByReal) {
+    for (const claim of claims) {
+      const names = activeNamesByCell.get(claim.id) || [];
+      names.push(realName);
+      activeNamesByCell.set(claim.id, names);
+    }
+  }
+  for (const [cellId, names] of activeNamesByCell) {
+    if (names.length > 1) {
+      throw tmuxMigrationError('TMUX_MIGRATION_AMBIGUOUS',
+        `migrazione tmux ambigua per ${cellId}: piu sessioni legacy (${names.join(', ')})`);
+    }
+  }
+
+  const operations = [];
+  for (const [realName, claims] of claimsByReal) {
+    if (claims.length !== 1) {
+      throw tmuxMigrationError('TMUX_MIGRATION_AMBIGUOUS',
+        `migrazione tmux ambigua: ${realName} corrisponde a ${claims.map((c) => c.id).join(', ')}`);
+    }
+    const candidate = claims[0];
+    const owner = ownersBySafe.get(realName);
+    if (owner && owner !== candidate.id) {
+      throw tmuxMigrationError('TMUX_MIGRATION_AMBIGUOUS',
+        `migrazione tmux ambigua: ${realName} e gia assegnata a ${owner}`);
+    }
+    const legacyId = realByName.get(realName);
+    if (!/^\$[0-9]+$/.test(legacyId || '')) {
+      throw tmuxMigrationError('TMUX_MIGRATION_INVALID_ID',
+        `migrazione tmux bloccata per ${candidate.id}: session ID non valido`);
+    }
+    const safeId = realByName.get(candidate.safe);
+    if (safeId && safeId !== legacyId) {
+      throw tmuxMigrationError('TMUX_MIGRATION_TARGET_EXISTS',
+        `migrazione tmux bloccata per ${candidate.id}: target ${candidate.safe} gia esistente`);
+    }
+    operations.push({ ...candidate, legacyId, realName });
+  }
+
+  const migrated = [];
+  for (const operation of operations) {
+    const rn = await tmuxExec(tmuxBin,
+      ['rename-session', '-t', operation.legacyId, operation.safe], { env: minimalEnv() });
+    if (rn.err) {
+      throw tmuxMigrationError('TMUX_MIGRATION_RENAME_FAILED',
+        `migrazione tmux fallita per ${operation.id} (${boundedTmuxFailure(rn)})`);
+    }
+    migrated.push({ id: operation.id, from: operation.realName, to: operation.safe });
+  }
+  return {
+    migrated, reason: 'ok',
+    needsPersistence: legacyMap.size > 0 || migrated.length > 0,
+  };
+}
+
 // Policy caratteri del prompt send-keys (§9e): ammette stampabili + \t \n \r;
 // rifiuta ESC(0x1b) e gli altri byte di controllo (niente marker bracketed-paste
 // iniettabili). parseDefinitions caps solo la lunghezza: questo e' defense-in-depth.
@@ -243,6 +366,7 @@ module.exports = {
   promptCharsOk,
   composeClientInvocation,
   composeLaunchArgv,
+  migrateLegacyTmuxSessions,
   waitAlive,
   waitStablePane,
   injectPrompt,

package/lib/fleet/managed.js

@@ -61,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', shell: 'Shell' });
+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}$/;
 
 function validBaseUrl(value) {
@@ -128,6 +128,16 @@ const CATALOG = Object.freeze([
   { id: 'pi.ollama', client: 'pi', provider: 'ollama', label: 'Ollama local', auth: 'none', protocol: 'openai-completions', piProvider: 'ollama', requiresModel: true, core: true, piExtension: { baseUrl: 'http://127.0.0.1:11434/v1', apiKey: 'ollama' } },
   { id: 'pi.zai', client: 'pi', provider: 'zai', label: 'Z.AI', auth: 'ZAI_API_KEY', protocol: 'pi_native', piProvider: 'zai', core: true },
   { id: 'pi.custom', client: 'pi', provider: 'custom', label: 'Custom provider', auth: 'dynamic', protocol: 'openai-responses', protocols: ['openai-responses', 'anthropic-messages', 'openai-completions', 'google-generative-ai'], custom: true, core: true },
+
+  // Agy: client gestito primario (Linux/macOS non-Termux). Auth delegata al
+  // login locale del client (nessuno store letto/copiato). Nessun remote-control
+  // NexusCrew; permission default 'standard' (unsafe aggiunge --dangerously-skip-
+  // permissions, allineato agli altri client). NON e' un default seed (non va nel
+  // fleet.json fresco su piattaforme non supportate): viene aggiunto solo da un
+  // backfill platform-aware (builtin.js) su Linux/macOS non-Termux. Qui figura
+  // (core) per la UI; describeManaged lo dichiara non configurato altrove.
+  // Termux/Windows restano fuori dal primary: l'utente usa agy via shell.local.
+  { id: 'agy.native', client: 'agy', provider: 'native', label: 'Agy', auth: 'login', protocol: 'agy_native', core: true },
 ]);
 
 function profileFor(client, provider, credentialProfile) {
@@ -202,6 +212,18 @@ function defaultShellEngine() {
   };
 }
 
+// Engine Agy per il backfill platform-aware (builtin.js): standard di default,
+// auth delegata al login locale, niente remote-control. Non e' un default seed.
+function defaultAgyEngine() {
+  const profile = CATALOG.find((entry) => entry.id === 'agy.native');
+  return {
+    id: profile.id,
+    label: CLIENT_LABELS.agy,
+    rc: false,
+    managed: { client: 'agy', provider: 'native', model: '', permissionPolicy: 'standard' },
+  };
+}
+
 function parseAssignments(raw) {
   const out = {};
   for (const line of raw.split(/\r?\n/)) {
@@ -312,6 +334,17 @@ function shellLoginArgs(command) {
   return ['bash', 'zsh', 'sh', 'dash'].includes(path.basename(String(command || ''))) ? ['-l'] : [];
 }
 
+// Un command configurato deve vedere lo stesso ambiente della shell interattiva
+// che l'utente ottiene lasciando vuoto il campo. Con `-lc`, zsh non carica
+// `.zshrc`: alias e PATH user-locali (per esempio ~/.local/bin) spariscono e il
+// command esce 127 pur essendo disponibile nel terminale normale. I quattro
+// shell POSIX-like supportati vengono quindi avviati login+interactive+command;
+// shell custom conservano il contratto storico -lc.
+function shellConfiguredCommandArgs(command, raw) {
+  return ['bash', 'zsh', 'sh', 'dash'].includes(path.basename(String(command || '')))
+    ? ['-lic', raw] : ['-lc', raw];
+}
+
 // 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
@@ -474,17 +507,30 @@ function describeManaged(spec, cfg = {}) {
   const delegatedPiAuth = profile.client === 'pi' && profile.provider !== 'custom'
     && profile.delegatePiAuth !== false;
   const authConfigured = delegatedPiAuth || profile.auth === 'login' || profile.auth === 'none' || !!cred.value;
+  let configured = !!binary && authConfigured;
+  let reason = !binary ? `client ${profile.client} not found` : (!authConfigured
+    ? `credential ${cred.envKey} missing — set it on this device`
+    : 'ready');
+  // Agy e' un client primario supportato solo su Linux/macOS non-Termux.
+  // Rilevazione Termux via termuxRuntimePaths (non solo process.platform): un
+  // Node che riporta 'linux' sotto proot/Termux viene comunque intercettato.
+  if (normalized.client === 'agy') {
+    const platform = cfg.platform || process.platform;
+    const termux = platform === 'android' || termuxRuntimePaths(cfg.env || process.env, { platform, home }) !== null;
+    if (termux || (platform !== 'linux' && platform !== 'darwin')) {
+      configured = false;
+      reason = 'agy non supportato su questa piattaforma (usa shell.local con command agy)';
+    }
+  }
   return {
     client: profile.client, clientLabel: CLIENT_LABELS[profile.client], provider: profile.provider,
     credentialProfile: normalized.credentialProfile || '', model: normalized.model,
     permissionPolicy: normalized.permissionPolicy, protocol: normalized.protocol || profile.protocol,
     endpoint: normalized.baseUrl || profile.endpoint || '', auth: cred.envKey, authConfigured,
     credentialSource: authConfigured ? cred.source : 'missing',
-    configured: !!binary && authConfigured, models: [...(profile.models || [])], defaultModel: profile.model || '',
+    configured, models: [...(profile.models || [])], defaultModel: profile.model || '',
     binary: binary || '', displayName: normalized.displayName || profile.label,
-    reason: !binary ? `client ${profile.client} not found` : (!authConfigured
-      ? `credential ${cred.envKey} missing — set it on this device`
-      : 'ready'),
+    reason,
   };
 }
 
@@ -633,7 +679,7 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
   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 === 'claude' || spec.client === 'agy') args.push('--dangerously-skip-permissions');
     if (spec.client === 'codex' || spec.client === 'codex-vl') args.push('--dangerously-bypass-approvals-and-sandbox');
   }
   let shellOneShot = false;
@@ -641,7 +687,7 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     const raw = cell?.commands && typeof cell.commands[engineId] === 'string'
       ? cell.commands[engineId] : '';
     shellOneShot = raw.trim().length > 0;
-    if (shellOneShot) args.push('-lc', raw);
+    if (shellOneShot) args.push(...shellConfiguredCommandArgs(info.binary, raw));
     else args.push(...shellLoginArgs(info.binary));
   } else if (spec.client === 'claude') {
     if (spec.provider === 'native') {
@@ -759,6 +805,13 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     if (spec.provider !== 'native') args.push('--provider', spec.provider === 'custom' ? spec.providerId : profile.piProvider);
     if (model) args.push('--model', model);
     if (spec.provider === 'alibaba-token-plan' && model === 'qwen3.8-max-preview') args.push('--thinking', 'xhigh');
+  } else if (spec.client === 'agy') {
+    // Agy delega l'autenticazione al proprio login locale (auth: 'login'): niente
+    // env provider, niente credenziali copiate. Argv diretto: --model prima del
+    // prompt; --prompt-interactive e' l'ultima coppia (il prompt value e' accodato
+    // dal push generico qui sotto). Senza prompt parte il TUI interattivo `agy`.
+    if (model) args.push('--model', model);
+    if (cell?.prompt) args.push('--prompt-interactive');
   }
   if (spec.client !== 'shell' && cell?.prompt) args.push(cell.prompt);
   let command = info.binary;
@@ -789,8 +842,9 @@ 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, defaultShellEngine, describeManaged, describeCatalogCredential, discoverOllamaModels, resolveManagedEngine, needsExplicitNode,
+  defaultDefinitions, defaultShellEngine, defaultAgyEngine, describeManaged, describeCatalogCredential, discoverOllamaModels, resolveManagedEngine, needsExplicitNode,
   discoverPiModels, parseEnvFile, parseProviderShellFile, findBinary, publicCatalog, writePiProviderExtension,
   providerKeyPaths, parseProviderKeyFiles, credentialSources, credential,
-  ensureKimiClaudeConfig, ensureAlibabaClaudeConfig, resolveInteractiveShell, shellLoginArgs, ENV_KEY_RE,
+  ensureKimiClaudeConfig, ensureAlibabaClaudeConfig, resolveInteractiveShell,
+  shellLoginArgs, shellConfiguredCommandArgs, ENV_KEY_RE,
 };

package/lib/fleet/provider.js

@@ -16,7 +16,7 @@ async function selectProvider(cfg = {}) {
   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' });
-  if (!fleet.available) return disabled('fleet.json mancante o invalido (fail-closed)');
+  if (!fleet.available) return disabled(fleet.reason || 'fleet.json mancante o invalido (fail-closed)');
   return { mode: 'builtin', reason: 'NexusCrew builtin fleet', fleet };
 }
 

package/lib/fleet/runtime.js

@@ -21,7 +21,7 @@ const {
 } = require('./managed.js');
 const {
   httpError, minimalEnv, tmuxExec,
-  composeClientInvocation, composeLaunchArgv,
+  composeClientInvocation,
   waitAlive, waitStablePane, injectPrompt,
   redactSecrets, sanitizeEarlyDiagnostic,
 } = require('./launch.js');
@@ -216,39 +216,105 @@ function createBuiltinRuntime(ctx) {
       args: [path.join(__dirname, 'cell-exec.js'), '--socket', ticket.socketPath, '--nonce', ticket.nonce],
       env: {}, promptMode: 'managed-argv',
     };
-    const argv = composeLaunchArgv({ tmuxSession: cell.tmuxSession, realCwd, engine: tmuxLaunchEngine, cell });
-    argv.splice(2, 0, '-P', '-F', '#{pane_id}');
-    // 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.
-    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) {
+    const tmuxChild = composeClientInvocation(tmuxLaunchEngine, cell);
+
+    // Avvio staged (design §3.3): crea il pane con un placeholder inerte trusted
+    // (cell-hold.js), arma remain-on-exit window-local sul @N, poi respawn-pane -k
+    // verso cell-exec sul %N esatto. Cosi' remain-on-exit e' gia' ON quando il vero
+    // child puo' terminare: nessuna finestra scomparsa, nessun NEW_SESSION_FAILED
+    // che maschera l'exit reale. Il nome sessione e' gia' validato tmux-safe (v2
+    // per id puntati, definitions.js); gli step critici usano gli ID restituiti
+    // da tmux ($N/@N/%N). respawn-pane -k preserva il pane ID: il %N catturato
+    // qui resta valido per readiness e prompt. Nessuna shell string, nessun
+    // command/env/prompt del child nell'argv tmux (solo cell-hold, poi cell-exec
+    // via broker). Nessun sleep come sincronizzazione.
+    const CELL_HOLD = path.join(__dirname, 'cell-hold.js');
+    const create = await tmuxExec(tmuxBin,
+      ['new-session', '-d', '-s', cell.tmuxSession, '-c', realCwd,
+        '-P', '-F', '#{session_id}\t#{window_id}\t#{pane_id}',
+        process.execPath, CELL_HOLD],
+      { env: minimalEnv() });
+    if (create.err) {
+      // new-session fallita: nessuna sessione creata. Revoca il ticket (il child
+      // non partira' mai) prima di propagare l'errore.
+      try { await launchBroker.revoke?.(ticket.nonce); } catch (_) { /* best-effort */ }
       // Redazione (§9h): lo stderr di tmux puo' ecoare argv/env del comando lanciato.
-      const dup = /duplicate session/i.test(launch.stderr);
+      const dup = /duplicate session/i.test(create.stderr);
       const why = dup
         ? 'sessione già in esecuzione'
-        : `tmux new-session failed: ${redactSecrets(launch.stderr.trim() || launch.err.message, launchEngine, cell)}`;
+        : `tmux new-session failed: ${redactSecrets(create.stderr.trim() || create.err.message, launchEngine, cell)}`;
       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 };
+    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] : '';
+    const paneId = /^%[0-9]+$/.test(createdIds[2] || '') ? createdIds[2] : '';
+    const resolveSessionIdForCleanup = async () => {
+      if (sessionId) return sessionId;
+      // Output parziale anomalo: risali al $N da un @N/%N gia restituito. Come
+      // ultima recovery enumera id+nomi e usa il nome safe solo per SELEZIONARE
+      // l'id; kill-session non torna mai al target nominale richiesto.
+      for (const target of [paneId, windowId]) {
+        if (!target) continue;
+        const shown = await tmuxExec(tmuxBin,
+          ['display-message', '-p', '-t', target, '#{session_id}'],
+          { env: minimalEnv(), timeoutMs: 2000 });
+        const resolved = shown.stdout.trim();
+        if (!shown.err && /^\$[0-9]+$/.test(resolved)) return resolved;
+      }
+      const listed = await tmuxExec(tmuxBin,
+        ['list-sessions', '-F', '#{session_id}\t#{session_name}'],
+        { env: minimalEnv(), timeoutMs: 2000 });
+      if (listed.err) return '';
+      for (const line of listed.stdout.split('\n')) {
+        const [sid, name] = line.split('\t');
+        if (name === cell.tmuxSession && /^\$[0-9]+$/.test(sid || '')) return sid;
+      }
+      return '';
+    };
+    const cleanupLaunch = async () => {
+      const stableSessionId = await resolveSessionIdForCleanup();
+      if (stableSessionId) {
+        await tmuxExec(tmuxBin, ['kill-session', '-t', stableSessionId],
+          { env: minimalEnv(), timeoutMs: 2000 });
+      }
+      try { await launchBroker.revoke?.(ticket.nonce); } catch (_) { /* best-effort */ }
+    };
+    if (!sessionId || !windowId || !paneId) {
+      await cleanupLaunch();
+      throw httpError(500, 'tmux new-session: ID sessione/finestra/pane non restituito', null,
+        { phase: 'new-session', code: 'NEW_SESSION_FAILED' });
+    }
+    // Arma remain-on-exit window-local sul @N: la finestra esiste (il placeholder
+    // la tiene viva), quindi niente race con un child che termini nel frattempo.
+    const arm = await tmuxExec(tmuxBin,
+      ['set-option', '-w', '-t', windowId, 'remain-on-exit', 'on'],
+      { env: minimalEnv() });
+    if (arm.err) {
+      await cleanupLaunch();
+      throw httpError(500,
+        `tmux set-option remain-on-exit failed: ${redactSecrets(arm.stderr.trim() || arm.err.message, launchEngine, cell)}`,
+        null, { phase: 'new-session', code: 'NEW_SESSION_FAILED' });
+    }
+    // Sostituisci il placeholder con il vero child (cell-exec via broker) sul %N.
+    const respawn = await tmuxExec(tmuxBin,
+      ['respawn-pane', '-k', '-c', realCwd, '-t', paneId, tmuxChild.command, ...tmuxChild.args],
+      { env: minimalEnv() });
+    if (respawn.err) {
+      // respawn fallito dopo issue(): il nonce va revocato/consumato prima
+      // dell'errore (design §3.3), poi cleanup della sessione-pannello.
+      await cleanupLaunch();
+      throw httpError(500,
+        `tmux respawn-pane failed: ${redactSecrets(respawn.stderr.trim() || respawn.err.message, launchEngine, cell)}`,
+        null, { phase: 'new-session', code: 'NEW_SESSION_FAILED' });
     }
 
     // `tmux new-session -d` can return 0 even when the launched CLI exits a
     // moment later (missing login, bad model, incompatible provider).  Without
     // this readiness gate the PWA reported success and then showed nothing.
     // Always verify liveness, including cells without a system prompt.
-    const paneId = launch.stdout.trim().split('\n')[0] || '';
+
     const readiness = paneId.startsWith('%')
       ? await waitStablePane(tmuxBin, paneId, { env: minimalEnv(), readyMs })
       : { alive: await waitAlive(tmuxBin, cell.tmuxSession, { env: minimalEnv(), readyMs }), status: null, target: null };
@@ -261,10 +327,25 @@ function createBuiltinRuntime(ctx) {
       }
       // remain-on-exit era soltanto diagnostico: nessun pane morto deve restare
       // nella Fleet o nella lista tmux dopo aver raccolto l'errore.
-      await tmuxExec(tmuxBin, ['kill-session', '-t', `=${cell.tmuxSession}`], { env: minimalEnv(), timeoutMs: 2000 });
+      await cleanupLaunch();
       cache = { ...cache, at: 0 };
+      // Un command Shell completato rapidamente con exit 0 e' un one-shot
+      // riuscito. Qualunque altro exit immediato e' invece osservabile come
+      // errore strutturato: prima il runtime restituiva un falso successo e
+      // scartava proprio l'exit 127/diagnostica che servivano all'operatore.
+      if (launchEngine.shellOneShot && readiness.status === 0) {
+        return {
+          ok: true, cell: cellId, session: cell.tmuxSession, prompt: null,
+          oneShot: true, active: false, completed: true, exitCode: 0,
+        };
+      }
       const client = path.basename(launchEngine.clientBinary || launchEngine.command || 'client');
       const status = Number.isInteger(readiness.status) ? ` (exit ${readiness.status})` : '';
+      if (launchEngine.shellOneShot) {
+        throw httpError(500,
+          `comando Shell terminato subito${status}: ${diagnostic || 'verifica command, PATH e configurazione della shell'}`,
+          null, { phase: 'readiness', code: 'SHELL_COMMAND_FAILED' });
+      }
       // 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
@@ -278,6 +359,17 @@ function createBuiltinRuntime(ctx) {
         ['set-option', '-w', '-t', readiness.target, 'remain-on-exit', 'off'], { env: minimalEnv(), timeoutMs: 2000 });
     }
 
+    // Il command Shell e' partito ed e' ancora vivo dopo la finestra di
+    // readiness: la cella deve risultare attiva (per CLI interattive come agy),
+    // poi tornera' inattiva quando il processo terminera' naturalmente.
+    if (launchEngine.shellOneShot) {
+      cache = { ...cache, at: 0 };
+      return {
+        ok: true, cell: cellId, session: cell.tmuxSession, prompt: null,
+        oneShot: true, active: true, completed: false,
+      };
+    }
+
     // (6) prompt send-keys: bracketed-paste best-effort, target = pane id esatto
     // (fallback al nome sessione con match esatto '=' se tmux non ha stampato l'id).
     let prompt = null;

package/lib/mcp/tools.js

@@ -9,9 +9,11 @@
 // argomenti e orchestrazione delle chiamate via ctx.api. Ordine, nomi, schemi,
 // handler, identity gate e semantica read/write sono preservati EXACT.
 const path = require('node:path');
+const { codeOf, phaseOf } = require('../fleet/causes.js');
 const {
   NODE_ID_RE, orderedDeckMembers, fleetStatusPath, fleetCellsBySession,
-  routePath, topologyOwners, memberOwnerId, parseCellTarget, readCellDirectory,
+  routePath, topologyOwners, memberOwnerId, parseCellTarget, normalizeCellPayload,
+  readCellDirectory,
 } = require('./cells.js');
 
 // --- helper input tool (fail-closed) ------------------------------------------
@@ -57,6 +59,93 @@ function requireSession(session, tool, code = IDENTITY_CODE.MISSING) {
   );
 }
 
+// Il command Shell e' utile per diagnosticare una cella locale, ma puo'
+// contenere credenziali scritte per errore. Manteniamo la struttura operativa
+// e redigiamo flag/assegnazioni credential-shaped prima che il valore lasci il
+// bridge MCP. Nessun command entra mai nella directory federata nc_cells.
+function commandForDiagnostics(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) {
+    return { configured: false, value: null, redacted: false, truncated: false };
+  }
+  let value = raw.normalize('NFC').replace(/[\p{Cc}\p{Cf}]/gu, ' ').replace(/\s+/g, ' ').trim();
+  const before = value;
+  value = value
+    .replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]')
+    .replace(/((?:--)?(?:api[-_]?key|token|secret|password|credential))(\s*(?:=|:)\s*|\s+)(?:"[^"]*"|'[^']*'|\S+)/gi,
+      '$1$2[redacted]')
+    .replace(/\b([A-Za-z][A-Za-z0-9_]*(?:_API_KEY|_KEY|_TOKEN|_SECRET|_PASSWORD|_CREDENTIAL|_AUTH)[A-Za-z0-9_]*)\s*=\s*(?:"[^"]*"|'[^']*'|\S+)/gi,
+      '$1=[redacted]')
+    // env maiuscole generiche senza separatore prima del suffisso credenziale
+    // (ZAIKEY=, PASSWD=, MYPASS=, DATABASE_URL=...): coerente con
+    // lib/diagnostics/store.js, ma consuma anche valori quotati per intero.
+    .replace(/\b([A-Z][A-Z0-9_]{2,})\s*=\s*(?:"[^"]*"|'[^']*'|\S+)/g, '$1=[redacted]')
+    .replace(/\b(?:sk|xox[baprs]|gh[pousr]|npm)[_-][A-Za-z0-9_-]{8,}\b/g, '[redacted]');
+  const truncated = value.length > 4096;
+  if (truncated) value = value.slice(0, 4096);
+  return { configured: true, value, redacted: value !== before || truncated, truncated };
+}
+
+// Accetta soltanto i due eventi failure prodotti dal router Fleet e ricostruisce
+// una causa chiusa. Free text e meta ignoti vengono sempre scartati, anche se
+// arrivano da un runtime precedente o compromesso.
+function failureForDiagnostics(record, cell) {
+  if (!record || record.component !== 'fleet' || !record.meta || record.meta.cell !== cell) return null;
+  const at = typeof record.ts === 'string' && record.ts.length <= 64 ? record.ts : null;
+  const status = Number.isSafeInteger(record.meta.status) && record.meta.status >= 100 && record.meta.status <= 599
+    ? record.meta.status : null;
+  if (record.code === 'CELL_SPAWN_FAILED') {
+    return {
+      event: 'CELL_SPAWN_FAILED', at, status,
+      code: 'SPAWN_CLIENT_FAILED', phase: 'spawn-client',
+      errno: /^[A-Z][A-Z0-9_]{0,31}$/.test(String(record.meta.errno || '')) ? record.meta.errno : null,
+      client: /^[A-Za-z0-9._+-]{1,128}$/.test(String(record.meta.client || '')) ? record.meta.client : null,
+    };
+  }
+  if (record.code !== 'FLEET_ACTION_FAILED') return null;
+  return {
+    event: 'FLEET_ACTION_FAILED', at, status,
+    code: codeOf(record.meta.code), phase: phaseOf(record.meta.phase),
+  };
+}
+
+function lastFailureForCell(records, cell) {
+  if (!Array.isArray(records)) return null;
+  for (let i = records.length - 1; i >= 0; i -= 1) {
+    const failure = failureForDiagnostics(records[i], cell);
+    if (failure) return failure;
+  }
+  return null;
+}
+
+async function recentDiagnostics(ctx) {
+  const out = [];
+  let after = 0;
+  // Store bounded a 500 record: tre pagine da 200 coprono l'intero buffer senza
+  // una query illimitata e senza dipendere dalla modalita' verbose.
+  for (let page = 0; page < 3; page += 1) {
+    const payload = await ctx.api('GET', `/api/diagnostics/logs?after=${after}&limit=200`);
+    const records = Array.isArray(payload && payload.records) ? payload.records : [];
+    out.push(...records);
+    const cursor = Number.isSafeInteger(payload && payload.cursor) ? payload.cursor : after;
+    if (records.length < 200 || cursor <= after) break;
+    after = cursor;
+  }
+  return out.slice(-500);
+}
+
+// La diagnostica command/cause e' intenzionalmente locale: non deve neppure
+// interrogare la topologia o i proxy remoti. Questo helper costruisce la stessa
+// forma normalizzata di nc_cells usando soltanto config + /api/cells locali.
+async function readLocalCellDirectory(ctx, callerSession) {
+  const [config, payload] = await Promise.all([
+    ctx.api('GET', '/api/config'), ctx.api('GET', '/api/cells'),
+  ]);
+  const nodeId = String(config && config.instanceId || '');
+  if (!NODE_ID_RE.test(nodeId)) throw new Error('instanceId locale non disponibile');
+  const owner = { instanceId: nodeId, route: [], label: 'Local', stale: false };
+  return { nodeId, cells: normalizeCellPayload(payload, owner, callerSession) };
+}
+
 // --- definizione tool (prefisso nc_ anti-collisione) ---------------------------
 // annotations.readOnlyHint:true sui tool che non mutano nulla (§1).
 const TOOLS = [
@@ -206,7 +295,8 @@ const TOOLS = [
           const members = orderedDeckMembers(deck).map((member) => ({
             ...member,
             ownerId: memberOwnerId(member, source.owner, source.ownerTopology),
-          }));
+          })).filter((member) => member.ownerId === localNodeId
+            || (member.ownerId && viewerById.has(member.ownerId)));
           if (!members.some((member) => member.ownerId === localNodeId && member.tmuxSession === tmuxSession)) continue;
           decks.push({
             id: `${source.owner.instanceId}:${deck.name}`,
@@ -263,6 +353,53 @@ const TOOLS = [
       return readCellDirectory(ctx, callerSession);
     },
   },
+  {
+    name: 'nc_cell_diagnostics',
+    description: 'Diagnostica read-only target-specifica di una cella Fleet locale: command Shell redatto e ultima causa spawn/start bounded. Richiede un caller Fleet locale attivo; non attraversa la federazione.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'id owner-qualified locale restituito da nc_cells: <instanceId>:<cell>' },
+      },
+      required: ['target'],
+    },
+    annotations: { readOnlyHint: true },
+    async handler(args, ctx) {
+      const targetRef = parseCellTarget(argString(args, 'target', { required: true, max: 128 }));
+      if (!targetRef) throw new Error('target non valido: usa l\'id esatto restituito da nc_cells');
+      const identity = await ctx.identity();
+      const callerSession = requireSession(identity.session, 'nc_cell_diagnostics', identity.code);
+      const directory = await readLocalCellDirectory(ctx, callerSession);
+      const sender = directory.cells.find((cell) => cell.self && cell.active);
+      if (!sender) throw new Error('nc_cell_diagnostics: la sessione chiamante non e\' una cella Fleet attiva locale');
+      if (targetRef.instanceId !== directory.nodeId) {
+        throw new Error('nc_cell_diagnostics: target remoto rifiutato; i command non attraversano la federazione');
+      }
+      const target = directory.cells.find((cell) => cell.instanceId === targetRef.instanceId
+        && cell.cell === targetRef.cell);
+      if (!target) throw new Error('nc_cell_diagnostics: cella locale non trovata');
+
+      const [definitions, diagnostics] = await Promise.all([
+        ctx.api('GET', '/api/fleet/definitions'), recentDiagnostics(ctx),
+      ]);
+      const definition = Array.isArray(definitions && definitions.cells)
+        ? definitions.cells.find((cell) => cell && cell.id === target.cell) : null;
+      if (!definition || definition.tmuxSession !== target.tmuxSession || definition.engine !== target.engine) {
+        throw new Error('nc_cell_diagnostics: definizione locale incoerente o non disponibile');
+      }
+      const rawCommand = definition.commands && typeof definition.commands === 'object'
+        ? definition.commands[definition.engine] : '';
+      return {
+        target: target.id,
+        cell: target.cell,
+        tmuxSession: target.tmuxSession,
+        engine: target.engine,
+        active: target.active,
+        command: commandForDiagnostics(rawCommand),
+        lastFailure: lastFailureForCell(diagnostics, target.cell),
+      };
+    },
+  },
   {
     name: 'nc_send_cell',
     description: 'Invia e sottopone un messaggio a una cella Fleet attiva autorizzata. target deve essere l\'id esatto restituito da nc_cells; submitted non significa lavoro completato.',
@@ -346,4 +483,7 @@ const TOOLS = [
   },
 ];
 
-module.exports = { TOOLS, argString, requireSession, IDENTITY_CODE, IDENTITY_REMEDIATION };
+module.exports = {
+  TOOLS, argString, requireSession, commandForDiagnostics, failureForDiagnostics,
+  lastFailureForCell, readLocalCellDirectory, IDENTITY_CODE, IDENTITY_REMEDIATION,
+};