@mmmbuto/nexuscrew 0.8.27 → 0.8.29

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' });
+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) {
@@ -109,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 },
@@ -148,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) {
@@ -188,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/)) {
@@ -269,6 +283,35 @@ 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
@@ -422,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.
@@ -585,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) {
@@ -708,7 +760,7 @@ 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, cfg.env || process.env)) {
     command = cfg.nodeExecPath || process.execPath;
@@ -716,6 +768,7 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
   }
   return { ok: true, info, engine: {
     ...engine, command, args, env, promptMode: 'managed-argv', clientBinary: info.binary,
+    ...(spec.client === 'shell' ? { shellOneShot } : {}),
   } };
 }
 
@@ -724,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),
@@ -736,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.
@@ -60,10 +61,23 @@ function fleetRoutes(fleetP, cfg = {}) {
           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,
+          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 || {}) });
+      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) } : {}),
+      });
     }
   };
 

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/package.json

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