@mmmbuto/nexuscrew 0.8.27 → 0.8.29

package/lib/fleet/builtin.js

@@ -30,9 +30,10 @@ const os = require('node:os');
 const path = require('node:path');
 const {
   loadDefinitions, atomicWrite, CAPS, MAX_CELLS, validTmuxName,
+  resolveCwd, normalizeCwdRel, deriveCwdRel,
 } = require('./definitions.js');
 const {
-  publicCatalog, describeManaged, describeCatalogCredential,
+  publicCatalog, describeManaged, describeCatalogCredential, defaultShellEngine,
 } = require('./managed.js');
 const { validEnvKey } = require('./env-key.js');
 const { setCredential, removeCredential } = require('./credentials.js');
@@ -64,10 +65,24 @@ function draftFrom(defs) {
       ...c,
       ...(c.models ? { models: { ...c.models } } : {}),
       ...(c.permissionPolicies ? { permissionPolicies: { ...c.permissionPolicies } } : {}),
+      ...(c.commands ? { commands: { ...c.commands } } : {}),
     })),
   };
 }
 
+// Upgrade locale, idempotente e non distruttivo: installazioni gia' esistenti
+// ricevono l'engine standard Shell senza riscrivere celle o sostituire un id
+// scelto dall'utente. Se lo store e' pieno o la scrittura non e' possibile, il
+// bootstrap resta utilizzabile con le definizioni precedenti.
+function backfillShellEngine(defsPath, defs) {
+  if (!defs || defs.engines.some((engine) => engine.managed?.client === 'shell')) return defs;
+  if (defs.engines.some((engine) => engine.id === 'shell.local')) return defs;
+  if (defs.engines.length >= CAPS.MAX_ENGINES) return defs;
+  const draft = draftFrom(defs);
+  draft.engines.push(defaultShellEngine());
+  try { return atomicWrite(defsPath, draft); } catch (_) { return defs; }
+}
+
 // Applica engine + modello + policy come un'unica transizione. Ogni engine ricorda
 // il proprio ultimo modello E l'ultima policy; passando a un altro engine né
 // l'uno né l'altra attraversano il confine. La policy e' PER-CELL PER-ENGINE:
@@ -93,6 +108,103 @@ function applyCellTransition(target, engineId, { model, hasModel, policy, hasPol
   if (selected) target.model = selected; else delete target.model;
 }
 
+// ---------------------------------------------------------------------------
+// cwd portabile (design §4.3). resolveCellCwd riconcilia cwd (assoluta) e
+// cwdRel (home-relative) in una COPPIA COERENTE prima di ogni scrittura:
+//   - solo cwd (assoluta valida) -> deriva cwdRel
+//   - solo cwdRel (valida)        -> calcola la cwd assoluta target
+//   - entrambi                     -> devono risolvere allo STESSO realpath
+// La risoluzione finale passa SEMPRE da resolveCwd (INVARIATO: realpath su
+// entrambi i lati, confinamento sotto home, directory deve esistere, symlink
+// escape rifiutato). Nessuna creazione directory, nessun fallback a home o al
+// cwd del servizio, nessun rimappaggio automatico di path di altri device.
+// Restituisce { ok:true, cwd, cwdRel } oppure { ok:false, fail:{ reason, ... } }.
+// ---------------------------------------------------------------------------
+function resolveCellCwd(cell, home) {
+  if (!cell || typeof cell !== 'object' || Array.isArray(cell)) return { ok: false, fail: { reason: 'invalid-cell' } };
+  const hasCwd = typeof cell.cwd === 'string' && cell.cwd.length > 0;
+  const hasRel = typeof cell.cwdRel === 'string'; // '' == home, forma valida
+  if (!hasCwd && !hasRel) return { ok: false, fail: { reason: 'missing' } };
+  let relNorm = null;
+  if (hasRel) {
+    relNorm = normalizeCwdRel(cell.cwdRel);
+    if (relNorm === null) return { ok: false, fail: { reason: 'invalid-rel', cwdRel: cell.cwdRel } };
+  }
+  const realHome = resolveCwd(home, home);
+  if (!realHome) return { ok: false, fail: { reason: 'home-unavailable' } };
+  const realCwd = hasCwd ? resolveCwd(cell.cwd, home) : null;
+  const realFromRel = hasRel ? resolveCwd(path.join(realHome, relNorm), home) : null;
+  if (hasCwd && hasRel) {
+    if (!realCwd) return { ok: false, fail: { reason: 'invalid-cwd', cwd: cell.cwd } };
+    if (!realFromRel) return { ok: false, fail: { reason: 'invalid-rel', cwdRel: cell.cwdRel } };
+    if (realCwd !== realFromRel) return { ok: false, fail: { reason: 'mismatch', cwd: cell.cwd, cwdRel: cell.cwdRel } };
+    return { ok: true, cwd: realCwd, cwdRel: relNorm };
+  }
+  if (hasCwd) {
+    if (!realCwd) return { ok: false, fail: { reason: 'invalid-cwd', cwd: cell.cwd } };
+    const rel = deriveCwdRel(realCwd, realHome);
+    if (rel === null) return { ok: false, fail: { reason: 'not-under-home', cwd: cell.cwd } };
+    return { ok: true, cwd: realCwd, cwdRel: rel };
+  }
+  // solo cwdRel
+  if (!realFromRel) return { ok: false, fail: { reason: 'invalid-rel', cwdRel: cell.cwdRel } };
+  return { ok: true, cwd: realFromRel, cwdRel: relNorm };
+}
+
+// suggestion (hint azionabile, MAI applicato in automatico): il basename della
+// cwd fornita combacia con una directory esistente sotto la home locale ->
+// suggerisce quel rel. Altrimenti resta assente. Bounded (singolo segmento).
+function suggestCwdRel(failedCwd, home) {
+  try {
+    const base = path.basename(String(failedCwd || ''));
+    if (!base || normalizeCwdRel(base) === null) return undefined;
+    const realHome = resolveCwd(home, home);
+    if (!realHome) return undefined;
+    if (!resolveCwd(path.join(realHome, base), home)) return undefined;
+    return base;
+  } catch (_) { return undefined; }
+}
+
+// Costruisce l'errore strutturato fail-closed (code 'unportable-cwd'): per ogni
+// cella rifiutata riporta id, eventuale cwd fornita e suggestion bounded.
+// Nessun segreto: cwd e' operazionale (gia' esposta dal messaggio di launch in
+// runtime.js); hint testuale fisso. Nessun log su buffer diagnostici.
+function unportableCwdError(failures, home) {
+  const cells = failures.map(({ id, fail }) => {
+    const entry = { id };
+    const cwd = typeof fail.cwd === 'string' ? fail.cwd : undefined;
+    if (cwd !== undefined) entry.cwd = cwd;
+    const suggestion = suggestCwdRel(cwd, home);
+    if (suggestion) entry.suggestion = suggestion;
+    return entry;
+  });
+  return httpError(400, `cwd non portabile (deve esistere sotto la home) per: ${failures.map((f) => f.id).join(', ')}`, {
+    code: 'unportable-cwd',
+    cells,
+    hint: 'il percorso appartiene a un altro dispositivo o non esiste sotto la home di questo device: scegli una cartella sotto la home',
+  });
+}
+
+// Prevalida TUTTE le celle prima di mutate/atomicWrite: risolve cwd/cwdRel in
+// coppia coerente per ciascuna; al primo blocco lancia l'errore strutturato e
+// NESSUNA scrittura parziale avviene. Restituisce l'array di celle risolte
+// (con cwd realpath + cwdRel canonico), nell'ordine originale.
+function resolveCellsOrFail(cells, home) {
+  const failures = [];
+  const resolved = [];
+  for (const cell of cells) {
+    const r = resolveCellCwd(cell, home);
+    if (!r.ok) { failures.push({ id: cell.id || '?', fail: r.fail }); continue; }
+    const { cwd, cwdRel } = r;
+    const next = { ...cell };
+    next.cwd = cwd;
+    next.cwdRel = cwdRel;
+    resolved.push(next);
+  }
+  if (failures.length) throw unportableCwdError(failures, home);
+  return resolved;
+}
+
 // ---------------------------------------------------------------------------
 // createBuiltinFleet(cfg) — unica implementazione Fleet di NexusCrew.
 // cfg: { fleetDefsPath?, tmuxBin?, home?, builtinEnabled?, readonlyDefault?,
@@ -112,8 +224,9 @@ async function createBuiltinFleet(cfg = {}) {
   const launchBroker = cfg.launchBroker || createLaunchBroker({ ...cfg, home });
 
   // Bootstrap: fleet.json valido? garbage -> unavailable (fail-closed, design §7)
-  const boot = loadDefinitions(defsPath);
+  let boot = loadDefinitions(defsPath);
   if (!boot) return off;
+  if (!readonly()) boot = backfillShellEngine(defsPath, boot);
 
   // Adopt or create the shared server before exposing a mutable Fleet. Reapply
   // before every lifecycle mutation so an accidental config reload cannot
@@ -164,8 +277,8 @@ async function createBuiltinFleet(cfg = {}) {
     if (hasPolicy && opts.permissionPolicy !== 'standard' && opts.permissionPolicy !== 'unsafe') {
       throw httpError(400, 'permissionPolicy non valida (standard|unsafe)');
     }
-    if (hasPolicy && selectedEngine.managed?.client === 'pi' && opts.permissionPolicy !== 'standard') {
-      throw httpError(400, 'Pi supporta solo permissionPolicy standard');
+    if (hasPolicy && ['pi', 'shell'].includes(selectedEngine.managed?.client) && opts.permissionPolicy !== 'standard') {
+      throw httpError(400, `${selectedEngine.managed.client === 'shell' ? 'Shell' : 'Pi'} supporta solo permissionPolicy standard`);
     }
     await mutate(defs, (d) => applyCellTransition(findCell(d, cellId), engId, {
       model: opts.model, hasModel,
@@ -236,6 +349,10 @@ async function createBuiltinFleet(cfg = {}) {
           delete cell.permissionPolicies[id];
           if (!Object.keys(cell.permissionPolicies).length) delete cell.permissionPolicies;
         }
+        if (cell.commands && Object.prototype.hasOwnProperty.call(cell.commands, id)) {
+          delete cell.commands[id];
+          if (!Object.keys(cell.commands).length) delete cell.commands;
+        }
       }
     });
     return { ok: true };
@@ -245,7 +362,10 @@ async function createBuiltinFleet(cfg = {}) {
     if (readonly()) throw httpError(403, 'READONLY: define-cell bloccato');
     if (!def || typeof def !== 'object' || Array.isArray(def)) throw httpError(400, 'definizione cell mancante');
     if (def.id != null && findCell(reloadDefs(), def.id)) throw httpError(400, `cell esiste già: ${def.id}`);
-    await mutate(reloadDefs(), (d) => { d.cells.push(def); });
+    // cwd portabile fail-closed: risolve cwd/cwdRel in coppia coerente PRIMA di
+    // scrivere (nessuna scrittura parziale su input non portabile).
+    const [cellDef] = resolveCellsOrFail([def], home);
+    await mutate(reloadDefs(), (d) => { d.cells.push(cellDef); });
     return { ok: true, id: def.id };
   }
   async function editCell(id, patch) {
@@ -259,8 +379,37 @@ async function createBuiltinFleet(cfg = {}) {
     }
     const nextEngine = findEngine(defs, typeof patch?.engine === 'string' ? patch.engine : current.engine);
     if (Object.prototype.hasOwnProperty.call(patch || {}, 'permissionPolicy')
-      && patch.permissionPolicy === 'unsafe' && nextEngine?.managed?.client === 'pi') {
-      throw httpError(400, 'Pi supporta solo permissionPolicy standard');
+      && patch.permissionPolicy === 'unsafe' && ['pi', 'shell'].includes(nextEngine?.managed?.client)) {
+      throw httpError(400, `${nextEngine.managed.client === 'shell' ? 'Shell' : 'Pi'} supporta solo permissionPolicy standard`);
+    }
+    // cwd portabile fail-closed: se la patch tocca cwd/cwdRel, riconcilia in
+    // coppia coerente PRIMA di mutate. cwd/cwdRel non sono chiudibili (null):
+    // cwd e' obbligatoria, cwdRel e' canonica derivata. Prevalida => nessuna
+    // scrittura parziale.
+    const hasCwdPatch = !!(patch && Object.prototype.hasOwnProperty.call(patch, 'cwd'));
+    const hasRelPatch = !!(patch && Object.prototype.hasOwnProperty.call(patch, 'cwdRel'));
+    let resolvedCwd = null;
+    if (hasCwdPatch || hasRelPatch) {
+      const candidate = { id };
+      if (hasCwdPatch) {
+        if (typeof patch.cwd !== 'string' || !patch.cwd) {
+          throw unportableCwdError([{ id, fail: { reason: 'invalid-cwd', cwd: patch.cwd } }], home);
+        }
+        candidate.cwd = patch.cwd;
+      }
+      if (hasRelPatch) {
+        if (typeof patch.cwdRel !== 'string') {
+          throw unportableCwdError([{ id, fail: { reason: 'invalid-rel', cwdRel: patch.cwdRel } }], home);
+        }
+        candidate.cwdRel = patch.cwdRel;
+      }
+      // Se arriva una sola coordinata, quella e' la nuova sorgente autoritativa:
+      // l'altra va ricalcolata, non confrontata col valore persistito precedente.
+      // Solo quando la patch porta entrambe si verifica esplicitamente la
+      // coerenza della coppia. Questo rende possibile cambiare directory e la
+      // futura repair UI senza indebolire il controllo mismatch.
+      const [resolved] = resolveCellsOrFail([candidate], home);
+      resolvedCwd = { cwd: resolved.cwd, cwdRel: resolved.cwdRel };
     }
     await mutate(defs, (d) => {
       const target = findCell(d, id);
@@ -271,9 +420,10 @@ async function createBuiltinFleet(cfg = {}) {
         throw httpError(400, 'permissionPolicy non valida (standard|unsafe)');
       }
       for (const [key, value] of Object.entries(patch || {})) {
-        if (key === 'engine' || key === 'model' || key === 'permissionPolicy') continue;
+        if (key === 'engine' || key === 'model' || key === 'permissionPolicy' || key === 'cwd' || key === 'cwdRel') continue;
         if (value === null) delete target[key]; else target[key] = value;
       }
+      if (resolvedCwd) { target.cwd = resolvedCwd.cwd; target.cwdRel = resolvedCwd.cwdRel; }
       if (hasEngine || hasModel || hasPolicy) applyCellTransition(target, hasEngine ? patch.engine : target.engine, {
         model: patch?.model, hasModel,
         policy: hasPolicy ? patch.permissionPolicy : null,
@@ -292,7 +442,7 @@ async function createBuiltinFleet(cfg = {}) {
     if (!Array.isArray(cells) || cells.length < 1 || cells.length > MAX_CELLS) {
       throw httpError(400, `cells deve contenere 1..${MAX_CELLS} definizioni`);
     }
-    const allowed = new Set(['id', 'cwd', 'engine', 'boot', 'model', 'models', 'permissionPolicies', 'prompt']);
+    const allowed = new Set(['id', 'cwd', 'cwdRel', 'engine', 'boot', 'model', 'models', 'permissionPolicies', 'commands', 'prompt']);
     const seen = new Set();
     for (const cell of cells) {
       if (!cell || typeof cell !== 'object' || Array.isArray(cell)) throw httpError(400, 'definizione cell non valida');
@@ -307,6 +457,7 @@ async function createBuiltinFleet(cfg = {}) {
       referencedEngines.add(cell.engine);
       for (const id of Object.keys(cell.models || {})) referencedEngines.add(id);
       for (const id of Object.keys(cell.permissionPolicies || {})) referencedEngines.add(id);
+      for (const id of Object.keys(cell.commands || {})) referencedEngines.add(id);
     }
     const missingEngines = [...referencedEngines].filter((id) => !availableEngines.has(id)).sort();
     if (missingEngines.length) {
@@ -317,8 +468,13 @@ async function createBuiltinFleet(cfg = {}) {
     }
     const replaced = cells.filter((cell) => !!findCell(defs, cell.id)).map((cell) => cell.id);
     const created = cells.filter((cell) => !findCell(defs, cell.id)).map((cell) => cell.id);
+    // cwd portabile fail-closed: prevalida TUTTE le celle (cwd assoluta legacy
+    // oppure cwdRel portatile v3) prima di mutate. Al primo rifiuto nessuna
+    // scrittura parziale. v1/v2 portano cwd assoluta e vengono rifiutate in modo
+    // strutturato se non valide sul target (path di un altro device / inesistenti).
+    const resolvedCells = resolveCellsOrFail(cells, home);
     await mutate(defs, (draft) => {
-      for (const cell of cells) {
+      for (const cell of resolvedCells) {
         const index = draft.cells.findIndex((current) => current.id === cell.id);
         const next = { ...cell };
         if (index >= 0) {
@@ -464,8 +620,12 @@ async function createBuiltinFleet(cfg = {}) {
     if (defs.cells.some((c) => c.id === id)) throw httpError(409, `id cella già usato: ${id}`);
     const cwd = typeof b.cwd === 'string' && b.cwd.trim() ? b.cwd.trim() : home;
     const cellDef = { id, cwd, engine: engineId, boot: b.boot === true, tmuxSession };
+    // Import is a write boundary just like define/edit/restore. Resolve and
+    // confine the cwd before mutate so a foreign or missing path is never
+    // persisted as a cell that can only fail later at up().
+    const [resolvedCell] = resolveCellsOrFail([cellDef], home);
     try {
-      await mutate(defs, (d) => { d.cells.push(cellDef); });
+      await mutate(defs, (d) => { d.cells.push(resolvedCell); });
     } catch (e) { throw httpError(400, `import non valido: ${e.message}`); }
     return { ok: true, id, tmuxSession, imported: true };
   }
@@ -487,6 +647,8 @@ async function createBuiltinFleet(cfg = {}) {
         credentialUsedBy: [...usedBy].sort(),
       };
     });
+    // realHome una volta per le vista cwdRel/needsRepair (derivate, NON persistite).
+    const realHome = resolveCwd(home, home);
     return {
       schemaVersion: defs.schemaVersion,
       engines: defs.engines.map((e) => {
@@ -495,11 +657,34 @@ async function createBuiltinFleet(cfg = {}) {
         if (e.managed) out.managedInfo = describeManaged(e.managed, { ...cfg, home });
         return out;
       }),
-      cells: defs.cells.map((c) => ({
-        ...c,
-        ...(c.models ? { models: { ...c.models } } : {}),
-        ...(c.permissionPolicies ? { permissionPolicies: { ...c.permissionPolicies } } : {}),
-      })),
+      cells: defs.cells.map((c) => {
+        const out = {
+          ...c,
+          ...(c.models ? { models: { ...c.models } } : {}),
+          ...(c.permissionPolicies ? { permissionPolicies: { ...c.permissionPolicies } } : {}),
+          ...(c.commands ? { commands: { ...c.commands } } : {}),
+        };
+        // cwdRel portatile derivato (solo vista): per celle valide (cwd reale
+        // sotto home) espone il rel canonico; per celle persistite ma non
+        // valide/fuori home espone needsRepair:true. NESSUNA mutazione di
+        // fleet.json (la vista non scrive). cwdRel persistito e' sempre
+        // ricalcolato dal realpath (autoritativo) cosi' export e UI sono coerenti.
+        const realCwd = resolveCwd(c.cwd, home);
+        if (realCwd && realHome) {
+          const rel = deriveCwdRel(realCwd, realHome);
+          if (rel !== null) out.cwdRel = rel; else out.needsRepair = true;
+        } else {
+          out.needsRepair = true;
+        }
+        // Suggerimento azionabile ma mai applicato: se il basename della cwd
+        // foreign esiste gia' sotto la home target, la UI puo' offrirlo come
+        // cwdRel esplicita senza mostrare o reinviare il path sorgente.
+        if (out.needsRepair) {
+          const suggestion = suggestCwdRel(c.cwd, home);
+          if (suggestion) out.cwdSuggestion = suggestion;
+        }
+        return out;
+      }),
       managedCatalog,
       managedConfig: {
         providerSecretsPath: cfg.providerSecretsPath || path.join(home, '.nexuscrew', 'providers.env'),
@@ -571,7 +756,7 @@ async function createBuiltinFleet(cfg = {}) {
         rc: { type: 'boolean', required: false, default: false },
         managed: {
           type: 'object', requiredFor: 'managed',
-          client: { type: 'enum', values: ['claude', 'codex', 'codex-vl', 'pi'] },
+          client: { type: 'enum', values: ['claude', 'codex', 'codex-vl', 'pi', 'shell'] },
           provider: { type: 'catalog', source: 'managedCatalog' },
           credentialProfile: { type: 'string', required: false, max: 32 },
           model: { type: 'string', required: false, max: CAPS.MAX_MODEL_VAL_LEN },
@@ -603,11 +788,13 @@ async function createBuiltinFleet(cfg = {}) {
       cell: {
         id: { type: 'string', required: true, pattern: '^[A-Za-z0-9._-]{1,32}$', max: 32 },
         cwd: { type: 'string', required: true, max: CAPS.MAX_CWD_LEN, underHome: true },
+        cwdRel: { type: 'string', required: false, max: CAPS.MAX_CWD_LEN, portable: true, default: '' },
         engine: { type: 'string', required: true, ref: 'engine.id' },
         boot: { type: 'boolean', required: false, default: false },
         model: { type: 'string', required: false, max: CAPS.MAX_MODEL_VAL_LEN },
         models: { type: 'object', required: false, keyRef: 'engine.id', valueMax: CAPS.MAX_MODEL_VAL_LEN },
         permissionPolicies: { type: 'object', required: false, keyRef: 'engine.id', valueEnum: ['standard', 'unsafe'] },
+        commands: { type: 'object', required: false, keyRef: 'engine.id', valueMax: CAPS.MAX_CELL_COMMAND_LEN, managedClient: 'shell' },
         prompt: { type: 'string', required: false, max: CAPS.MAX_PROMPT_LEN },
       },
     };
@@ -632,6 +819,8 @@ async function createBuiltinFleet(cfg = {}) {
 
 module.exports = {
   createBuiltinFleet,
+  backfillShellEngine,
+  resolveCellCwd,
   composeLaunchArgv,
   composeClientInvocation,
   minimalEnv,

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.
@@ -45,6 +63,7 @@ const REDACTED = '‹redacted›';
 //  - valori di engine.env           (le CHIAVI restano, i VALUES vengono redatti)
 //  - testo del prompt della cella   (cell.prompt)
 //  - testo del prompt dell'engine   (engine.prompt) se presente
+//  - comando Shell attivo per cella (cell.commands[cell.engine])
 // Applicato a OGNI messaggio d'errore che incorpora stderr/stdout dei comandi
 // tmux falliti (up / down / injectPrompt): tmux puo' ecoare argv/env del comando
 // lanciato nei suoi log di errore. Pura + senza dipendenze: testabile direttamente.
@@ -58,6 +77,11 @@ function redactSecrets(text, engine, cell) {
   }
   if (engine && typeof engine.prompt === 'string' && engine.prompt) secrets.push(engine.prompt);
   if (cell && typeof cell.prompt === 'string' && cell.prompt) secrets.push(cell.prompt);
+  if (cell && typeof cell.engine === 'string'
+      && cell.commands && typeof cell.commands === 'object' && !Array.isArray(cell.commands)) {
+    const activeCommand = cell.commands[cell.engine];
+    if (typeof activeCommand === 'string' && activeCommand) secrets.push(activeCommand);
+  }
   // Ordina per lunghezza DECRESCENTE: i segreti piu' lunghi prima, cosi' un segreto
   // che e' prefisso/sottostringa di un altro non ne maschera il rimpiazzo completo.
   secrets.sort((a, b) => b.length - a.length);