@mmmbuto/nexuscrew 0.8.27 → 0.8.28

package/lib/fleet/causes.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// Cause-preserving diagnostics for Fleet up() failures (T4).
+//
+// The up() path of the built-in fleet crosses five boundaries:
+//   1. preflight gates          (command trust, cwd, managed-engine config)
+//   2. the secure launch broker (private runtime dir, payload, lifecycle)
+//   3. tmux new-session         (session creation / duplicate)
+//   4. pane/client early-exit   (readiness / liveness gate)
+//   5. the cell client spawn    (ENOENT/EACCES/... surfaced via cell-exec)
+//
+// When one of them failed, the cause used to be buried in a free-text error
+// message.  These bounded enums travel on structured HTTP errors instead, so
+// FLEET_ACTION_FAILED can report a closed {status, code, phase} triple that
+// NEVER embeds cwd/path, argv, env, prompt, token or credential data — only
+// stable enum strings, which are safe to persist and to show.
+//
+// Add a value here ONLY when a new reachable boundary needs a stable cause.
+// Anything not in the enum degrades to UNKNOWN (bounded) at the coercion gate,
+// so an untagged/legacy/unexpected error can never leak an unbounded string.
+
+const UNKNOWN = 'UNKNOWN';
+
+// Lifecycle phase of up() where a boundary failed.  Closed enum.
+//   preflight      -> pre-launch validation gates
+//   launch-broker  -> secure launch broker
+//   new-session    -> tmux new-session creation
+//   readiness      -> pane/client early-exit liveness gate
+//   spawn-client   -> cell client spawn error surfaced via cell-exec
+const PHASES = ['preflight', 'launch-broker', 'new-session', 'readiness', 'spawn-client'];
+const PHASE_SET = new Set(PHASES);
+
+// Stable failure code per boundary.  Closed enum; free text never enters here.
+const CODES = [
+  // preflight (pre-launch gates)
+  'COMMAND_UNTRUSTED',
+  'CWD_INVALID',
+  'ENGINE_UNCONFIGURED',
+  'SHELL_NOT_AVAILABLE',
+  // launch-broker
+  'LAUNCH_BROKER_UNSAFE',
+  'LAUNCH_BROKER_PAYLOAD',
+  'LAUNCH_BROKER_CLOSED',
+  'LAUNCH_BROKER_FAILED',
+  // new-session
+  'NEW_SESSION_FAILED',
+  'SESSION_DUPLICATE',
+  // readiness (client started but exited immediately)
+  'CLIENT_EARLY_EXIT',
+  // spawn-client (cell client spawn error: ENOENT/EACCES/...)
+  'SPAWN_CLIENT_FAILED',
+  // bounded fallback for any untagged / legacy / unexpected error
+  UNKNOWN,
+];
+const CODE_SET = new Set(CODES);
+
+function coerce(value, allowed, fallback) {
+  return typeof value === 'string' && allowed.has(value) ? value : fallback;
+}
+
+// Coerce a raw code/phase to the bounded enum, degrading to UNKNOWN.
+// Pure + without dependencies: testable directly.
+function codeOf(value) { return coerce(value, CODE_SET, UNKNOWN); }
+function phaseOf(value) { return coerce(value, PHASE_SET, UNKNOWN); }
+
+module.exports = {
+  UNKNOWN, PHASES, CODES, codeOf, phaseOf,
+};

package/lib/fleet/definitions.js

@@ -29,6 +29,7 @@ const MAX_MODEL_FLAG_LEN = 32;
 const MAX_MODEL_VAL_LEN = 128;
 const MAX_PROMPTFLAG_LEN = 32;
 const MAX_PROMPT_LEN = 8192;   // 8 KB
+const MAX_CELL_COMMAND_LEN = 4096;
 const MAX_TMUXSESSION_LEN = 64;
 
 const ENGINE_ID_RE = /^[a-z0-9._-]{1,32}$/;   // engine id: lowercase (design 4a/9f)
@@ -97,12 +98,14 @@ function parseDefinitions(raw) {
     if (d.cells.length > MAX_CELLS) return null;
 
     const engineIds = new Set();
+    const engineMap = new Map();
     const engines = [];
     for (const e of d.engines) {
       const eng = parseEngine(e);
       if (!eng) return null;
       if (engineIds.has(eng.id)) return null;            // id engine univoco
       engineIds.add(eng.id);
+      engineMap.set(eng.id, eng);
       engines.push(eng);
     }
 
@@ -110,7 +113,7 @@ function parseDefinitions(raw) {
     const cellIds = new Set();
     const cells = [];
     for (const c of d.cells) {
-      const cell = parseCell(c, engineIds);
+      const cell = parseCell(c, engineIds, engineMap);
       if (!cell) return null;
       if (cellIds.has(cell.id)) return null;             // id cell univoco
       cellIds.add(cell.id);
@@ -215,7 +218,7 @@ function parseEngine(e) {
   return out;
 }
 
-function parseCell(c, engineIds) {
+function parseCell(c, engineIds, engineMap = new Map()) {
   if (!c || typeof c !== 'object' || Array.isArray(c)) return null;
 
   // id
@@ -224,6 +227,18 @@ function parseCell(c, engineIds) {
   // cwd (obbligatorio; la risoluzione/confinamento avviene via resolveCwd a runtime)
   if (typeof c.cwd !== 'string' || !c.cwd || c.cwd.length > MAX_CWD_LEN) return null;
 
+  // cwdRel (opzionale canonico, design §4.3): forma portatile home-relative.
+  // Qui si valida solo il FORMATO (stringa canonica): la coerenza cwd<->cwdRel
+  // e' un invariante di SCRITTURA (define/edit/restore), non di lettura — così
+  // le definizioni legacy (solo cwd) e quelle nuove (cwd+cwdRel) caricano senza
+  // riscrittura on-read e senza rendere il file illeggibile per disallineamenti.
+  let cwdRel;
+  if (c.cwdRel !== undefined) {
+    if (typeof c.cwdRel !== 'string') return null;
+    cwdRel = normalizeCwdRel(c.cwdRel);
+    if (cwdRel === null) return null;
+  }
+
   // engine = riferimento a engines[].id esistente (dangling -> null)
   if (typeof c.engine !== 'string' || !engineIds.has(c.engine)) return null;
 
@@ -268,10 +283,27 @@ function parseCell(c, engineIds) {
     for (const [engineId, value] of entries) {
       if (!engineIds.has(engineId)) return null;
       if (value !== 'standard' && value !== 'unsafe') return null;
+      if (engineMap.get(engineId)?.managed?.client === 'shell' && value !== 'standard') return null;
       permissionPolicies[engineId] = value;
     }
   }
 
+  // commands: comando Shell PER-CELL PER-ENGINE. La stringa resta opaca e
+  // viene interpretata solo dalla shell target con `-lc`; qui si applicano
+  // limiti e forma chiusa. Sono ammesse soltanto chiavi di engine Shell.
+  let commands;
+  if (c.commands !== undefined) {
+    if (!c.commands || typeof c.commands !== 'object' || Array.isArray(c.commands)) return null;
+    const entries = Object.entries(c.commands);
+    if (entries.length > MAX_ENGINES) return null;
+    commands = {};
+    for (const [engineId, value] of entries) {
+      if (!engineIds.has(engineId) || engineMap.get(engineId)?.managed?.client !== 'shell') return null;
+      if (typeof value !== 'string' || value.length > MAX_CELL_COMMAND_LEN || /[\x00-\x1f\x7f]/.test(value)) return null;
+      commands[engineId] = value;
+    }
+  }
+
   // prompt (opzionale, cap)
   let prompt;
   if (c.prompt !== undefined) {
@@ -296,9 +328,11 @@ function parseCell(c, engineIds) {
   }
 
   const out = { id: c.id, cwd: c.cwd, engine: c.engine, boot, tmuxSession };
+  if (cwdRel !== undefined) out.cwdRel = cwdRel;
   if (model !== undefined) out.model = model;
   if (Object.keys(models).length) out.models = models;
   if (permissionPolicies) out.permissionPolicies = permissionPolicies;
+  if (commands && Object.keys(commands).length) out.commands = commands;
   if (prompt !== undefined) out.prompt = prompt;
   return out;
 }
@@ -345,6 +379,52 @@ function resolveCwd(cwd, home) {
   } catch (_) { return null; }
 }
 
+// ---------------------------------------------------------------------------
+// cwdRel — cwd home-relative PORTATILE (design §4.3 / backup v3).
+// Rappresentazione canonica di una cwd come percorso relativo alla home del
+// device target: '' == la home stessa; 'personal' == <home>/personal.
+// Helper PURI (nessun fs): la normalizzazione e' string-only e fail-closed.
+// La risoluzione/confinamento finale resta demandata a resolveCwd (realpath su
+// entrambi i lati), INVARIATO: cwdRel aggiunge un vincolo in scrittura, non lo
+// indebolisce in lettura. Nessun '..'/assoluto/control/backslash/drive letter.
+// ---------------------------------------------------------------------------
+// Restituisce la forma canonica ('' = home) oppure null (input non portabile).
+// Normalizza (collassa '.' e segmenti vuoti, scosta lo slash finale) RIFIUTANDO
+// traversal, path assoluti, drive letter (Win), NUL/C0/DEL e backslash.
+function normalizeCwdRel(rel, maxLen = MAX_CWD_LEN) {
+  if (typeof rel !== 'string') return null;
+  if (rel.length > maxLen) return null;
+  for (let i = 0; i < rel.length; i += 1) {
+    const c = rel.charCodeAt(i);
+    if (c <= 0x1f || c === 0x7f || c === 0x5c) return null; // C0, DEL, backslash
+  }
+  if (rel === '') return ''; // la home stessa
+  if (rel.charAt(0) === '/') return null; // path assoluto (leading sep)
+  if (/^[A-Za-z]:/.test(rel)) return null; // drive letter (Win-like)
+  const out = [];
+  for (const seg of rel.split('/')) {
+    if (seg === '' || seg === '.') continue; // collassa vuoti/dot
+    if (seg === '..') return null; // traversal
+    out.push(seg);
+  }
+  return out.join('/');
+}
+
+// Deriva il cwdRel canonico da una cwd ASSOLUTA rispetto a una home (entrambe
+// gia' realpath: il caller passa realpath). Restituisce '' (== home), un rel
+// normalizzato, oppure null se la cwd non e' esprimibile sotto la home.
+// Pura: nessun fs. Usa path.relative sulle stringhe (sicuro perche' entrambi
+// realpath e cwd confinato sotto home).
+function deriveCwdRel(absCwd, home) {
+  if (typeof absCwd !== 'string' || !absCwd || typeof home !== 'string' || !home) return null;
+  if (absCwd.includes('\0') || home.includes('\0')) return null;
+  const rel = path.relative(home, absCwd);
+  if (rel === '') return ''; // cwd == home
+  if (path.isAbsolute(rel)) return null; // drive diverso (Win)
+  if (rel === '..' || rel.startsWith('..' + path.sep)) return null; // fuori home
+  return normalizeCwdRel(rel);
+}
+
 // ---------------------------------------------------------------------------
 // loadDefinitions(p) -> parsed | null
 // Legge il file rifiutando i symlink; parse strict. Mai throw.
@@ -413,18 +493,20 @@ const CAPS = {
   SCHEMA_VERSION, MAX_ENGINES, MAX_CELLS, MAX_ARGS, MAX_ARG_LEN,
   MAX_ENV_KEYS, MAX_ENV_KEY_LEN, MAX_ENV_VAL_LEN, MAX_LABEL_LEN,
   MAX_COMMAND_LEN, MAX_CWD_LEN, MAX_MODEL_FLAG_LEN, MAX_MODEL_VAL_LEN,
-  MAX_PROMPTFLAG_LEN, MAX_PROMPT_LEN, MAX_TMUXSESSION_LEN,
+  MAX_PROMPTFLAG_LEN, MAX_PROMPT_LEN, MAX_CELL_COMMAND_LEN, MAX_TMUXSESSION_LEN,
 };
 
 module.exports = {
   parseDefinitions,
   validateCommandTrust,
   resolveCwd,
+  normalizeCwdRel,
+  deriveCwdRel,
   loadDefinitions,
   atomicWrite,
   validTmuxName,
   CAPS,
   // Costanti esposte anche piatte (comode per la UI/schema e i test)
   SCHEMA_VERSION, MAX_ENGINES, MAX_CELLS, MAX_ARGS, MAX_ARG_LEN,
-  MAX_ENV_KEYS, MAX_ENV_KEY_LEN, MAX_ENV_VAL_LEN, MAX_PROMPT_LEN,
+  MAX_ENV_KEYS, MAX_ENV_KEY_LEN, MAX_ENV_VAL_LEN, MAX_PROMPT_LEN, MAX_CELL_COMMAND_LEN,
 };

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

@@ -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.28",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {