npm - @mmmbuto/nexuscrew - Versions diffs - 0.8.27 → 0.8.28 - Mend

@mmmbuto/nexuscrew 0.8.27 → 0.8.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/CHANGELOG.md +23 -0
package/README.md +23 -8
package/frontend/dist/assets/{index-xxfypte7.css → index-BAzlX2nP.css} +1 -1
package/frontend/dist/assets/index-DiKMLCvW.js +93 -0
package/frontend/dist/index.html +2 -2
package/frontend/dist/version.json +1 -1
package/lib/cli/commands.js +19 -2
package/lib/cli/doctor.js +98 -11
package/lib/cli/service.js +7 -4
package/lib/diagnostics/store.js +1 -1
package/lib/fleet/builtin.js +201 -16
package/lib/fleet/causes.js +68 -0
package/lib/fleet/definitions.js +86 -4
package/lib/fleet/launch.js +19 -1
package/lib/fleet/managed.js +62 -9
package/lib/fleet/routes.js +16 -2
package/lib/fleet/runtime.js +69 -33
package/package.json +1 -1
package/frontend/dist/assets/index-CWKyv6KS.js +0 -93

package/frontend/dist/index.html CHANGED Viewed

@@ -11,8 +11,8 @@
   <meta name="apple-mobile-web-app-title" content="NexusCrew" />
   <link rel="manifest" href="/manifest.json" />
   <title>NexusCrew</title>
-  <script type="module" crossorigin src="/assets/index-CWKyv6KS.js"></script>
-  <link rel="stylesheet" crossorigin href="/assets/index-xxfypte7.css">
+  <script type="module" crossorigin src="/assets/index-DiKMLCvW.js"></script>
+  <link rel="stylesheet" crossorigin href="/assets/index-BAzlX2nP.css">
 </head>
 <body>
   <div id="root"></div>

package/frontend/dist/version.json CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":"0.8.27"}
1	+ {"version":"0.8.28"}

package/lib/cli/commands.js CHANGED Viewed

@@ -14,7 +14,7 @@ const pidf = require('./pidfile.js');
 const { runInit, ensureFleetDefaults } = require('./init.js');
 const { rotateToken } = require('../auth/token.js');
 const urlmod = require('./url.js');
-const { doctor } = require('./doctor.js');
+const { doctor, checkServiceWorkingDirectory } = require('./doctor.js');
 const nodesStore = require('../nodes/store.js');
 const nodesTunnel = require('../nodes/tunnel.js');
 const nodesCmds = require('../nodes/commands.js');
@@ -346,6 +346,11 @@ function servicePinsLegacyPort(platform, home, installPath) {
   try { return /NEXUSCREW_PORT/.test(fs.readFileSync(target, 'utf8')); } catch (_) { return false; }
 }
+function serviceDefinitionNeedsRefresh(platform, home, installPath) {
+  if (servicePinsLegacyPort(platform, home, installPath)) return true;
+  return !checkServiceWorkingDirectory(platform, home, installPath).ok;
+}
 function portAvailable(port, host = '127.0.0.1') {
   return new Promise((resolve) => {
     const s = net.createServer();
@@ -465,8 +470,19 @@ async function smartUp(opts = {}) {
   // config.json forever. Regenerate once so config.json becomes authoritative.
   const home = opts.home || require('node:os').homedir();
   const persistent = bootState({ ...opts, platform }).enabled;
-  if (persistent && servicePinsLegacyPort(platform, home, opts.installPath)) {
+  let serviceRefreshed = false;
+  if (persistent && serviceDefinitionNeedsRefresh(platform, home, opts.installPath)) {
     runInitImpl({ ...opts, log: quiet, platform, installBoot: true, printUrl: false });
+    serviceRefreshed = checkServiceWorkingDirectory(platform, home, opts.installPath).ok;
+    // Termux:Boot has no service manager, so replacing the script alone cannot
+    // change the cwd of the already-running pidfile owner. Restart exactly once
+    // after a verified migration; Linux/macOS are restarted by installService.
+    if (serviceRefreshed && platform === 'termux') {
+      const migrated = restartImpl({ ...opts, platform, log: quiet });
+      if (!migrated || migrated.restarted !== true) {
+        throw new Error(`service cwd migration restart failed: ${(migrated && migrated.reason) || 'unknown'}`);
+      }
+    }
   }
   if (!port) port = urlmod.loadPort(opts);
@@ -972,6 +988,7 @@ function dispatch(argv, opts = {}) {
 module.exports = {
   dispatch, dispatchNodes, serve, start, stop, status, parseFlags, HELP, NODES_HELP,
   smartUp, url, tokenRotate, logs, doctor, update, restart,
+  serviceDefinitionNeedsRefresh,
   portAvailable, findAvailablePort, probeNexusCrew, waitForNexusCrew, openPwa, startPortable, wizardComplete,
   servicePinsLegacyPort,
   isServiceRunning, readRoles,

package/lib/cli/doctor.js CHANGED Viewed

@@ -79,22 +79,50 @@ function checkMacServiceWorkingDirectory(platform, home, installPathOverride) {
   if (platform !== 'mac') {
     return { name: 'launchd cwd stabile', ok: true, detail: `${platform}: non applicabile` };
   }
-  const target = installPathOverride || installPath('mac', home);
+  return checkServiceWorkingDirectory(platform, home, installPathOverride);
+}
+// The service cwd is inherited by a shared tmux server and every future pane.
+// It must therefore be HOME, never the replaceable runtime directory. This
+// check reads only the installed definition and fails closed on missing,
+// symlinked, malformed, or legacy service files.
+function checkServiceWorkingDirectory(platform, home, installPathOverride) {
+  if (!['linux', 'mac', 'termux'].includes(platform)) {
+    return { name: 'service cwd stabile', ok: true, detail: `${platform}: non applicabile` };
+  }
+  const target = installPathOverride || installPath(platform, home);
   let raw;
-  try { raw = fs.readFileSync(target, 'utf8'); }
+  try {
+    const st = fs.lstatSync(target);
+    if (st.isSymbolicLink() || !st.isFile()) throw Object.assign(new Error('definizione service non regolare'), { code: 'UNSAFE' });
+    raw = fs.readFileSync(target, 'utf8');
+  }
   catch (error) {
     return {
-      name: 'launchd cwd stabile', ok: false,
-      detail: error.code === 'ENOENT' ? `plist non installato (${target})` : error.message,
+      name: 'service cwd stabile', ok: false,
+      detail: error.code === 'ENOENT' ? `service non installato (${target})` : error.message,
     };
   }
-  const match = raw.match(/<key>WorkingDirectory<\/key>\s*<string>([\s\S]*?)<\/string>/);
-  if (!match) return { name: 'launchd cwd stabile', ok: false, detail: 'WorkingDirectory assente dal plist' };
-  const actual = decodeXmlText(match[1]);
-  const expected = String(home);
+  let actual = '';
+  let ok = false;
+  if (platform === 'mac') {
+    const match = raw.match(/<key>WorkingDirectory<\/key>\s*<string>([\s\S]*?)<\/string>/);
+    if (!match) return { name: 'service cwd stabile', ok: false, detail: 'WorkingDirectory assente dal plist' };
+    actual = decodeXmlText(match[1]);
+    ok = actual === String(home);
+  } else if (platform === 'linux') {
+    const match = raw.match(/^WorkingDirectory=(.+)$/m);
+    if (!match) return { name: 'service cwd stabile', ok: false, detail: 'WorkingDirectory assente dalla unit' };
+    actual = match[1].replace(/%%/g, '%');
+    ok = actual === String(home);
+  } else {
+    const stable = /^\s*cd -- "\$HOME"\s*$/m.test(raw);
+    actual = stable ? '$HOME' : (/^\s*cd\s+--\s+(.+)$/m.exec(raw)?.[1] || 'cd assente');
+    ok = stable;
+  }
   return {
-    name: 'launchd cwd stabile', ok: actual === expected,
-    detail: actual === expected ? expected : `${actual} (atteso HOME stabile: ${expected})`,
+    name: 'service cwd stabile', ok,
+    detail: ok ? (platform === 'termux' ? '$HOME' : String(home)) : `${actual} (atteso HOME stabile)`,
   };
 }
@@ -261,6 +289,61 @@ function checkTermuxExec(runtimeEnv, opts = {}) {
   };
 }
+// Read-only probe of the long-lived tmux server cwd. A server that retained an
+// unlinked runtime directory keeps accepting clients but makes later children
+// fail getcwd(3). Never reports the path itself; only stable state.
+function checkTmuxServerCwd(platform, execImpl, opts = {}) {
+  if (!['linux', 'termux'].includes(platform)) {
+    return { name: 'tmux server cwd', ok: true, detail: `${platform}: non applicabile` };
+  }
+  let rawPid = '';
+  try {
+    rawPid = String(execImpl(opts.tmuxBin || 'tmux', ['display-message', '-p', '#{pid}'], { encoding: 'utf8' }) || '').trim();
+  } catch (_) {
+    return { name: 'tmux server cwd', ok: true, warn: true, detail: 'server tmux non attivo; probe rinviato al primo avvio' };
+  }
+  if (!/^\d+$/.test(rawPid)) {
+    return { name: 'tmux server cwd', ok: true, warn: true, detail: 'server tmux non rilevato' };
+  }
+  try {
+    const resolveImpl = opts.procCwdImpl || ((pid) => fs.realpathSync(`/proc/${pid}/cwd`));
+    const cwd = resolveImpl(Number(rawPid));
+    if (typeof cwd !== 'string' || !cwd) throw new Error('cwd vuota');
+    return { name: 'tmux server cwd', ok: true, detail: 'cwd risolvibile' };
+  } catch (_) {
+    return {
+      name: 'tmux server cwd', ok: false,
+      detail: 'cwd del server tmux non risolvibile (directory sostituita); termina le sessioni in modo esplicito e riavvia tmux',
+    };
+  }
+}
+// Inspect only the single tmux global environment key required by
+// termux-exec. The value is validated and then discarded; it is never logged.
+// This distinguishes a healthy server from RC-2 (stale/no preload) and RC-7
+// (present but rejected by the trust boundary) without killing any session.
+function checkTmuxServerTermuxPreload(runtimeEnv, execImpl, opts = {}) {
+  const env = runtimeEnv || process.env;
+  const platform = opts.platform || detectPlatform();
+  if (!termuxRuntimePaths(env, { platform, home: opts.home })) {
+    return { name: 'tmux server termux-exec', ok: true, detail: `${platform}: non applicabile` };
+  }
+  let raw = '';
+  try {
+    raw = String(execImpl(opts.tmuxBin || 'tmux', ['show-environment', '-g', 'LD_PRELOAD'], { encoding: 'utf8' }) || '').trim();
+  } catch (_) {
+    return { name: 'tmux server termux-exec', ok: true, warn: true, detail: 'server tmux non attivo; probe rinviato al primo avvio' };
+  }
+  const match = raw.match(/^LD_PRELOAD=(.+)$/);
+  const trusted = match && trustedTermuxPreload({ ...env, LD_PRELOAD: match[1] }, { platform, home: opts.home });
+  return trusted
+    ? { name: 'tmux server termux-exec', ok: true, detail: 'preload trusted presente nel server tmux' }
+    : {
+      name: 'tmux server termux-exec', ok: false,
+      detail: 'LD_PRELOAD assente o non trusted nel server tmux; server stale o formato non compatibile (nessun kill automatico)',
+    };
+}
 // Check MCP identity (P0). NON-FAILING per costrutto: `ok` è sempre true, così
 // chi usa NexusCrew solo come PWA (nessuna integrazione MCP) non vede mai il
 // doctor andare in FAIL solo per env MCP assente. Il check osserva SOLO la
@@ -341,7 +424,7 @@ function doctor(opts = {}) {
     checkTmux(existsImpl, opts.tmuxBin),
     checkPty(ptyLoad),
     checkService(platform, home, execImpl, uidVal, opts.installPath),
-    checkMacServiceWorkingDirectory(platform, home, opts.installPath),
+    checkServiceWorkingDirectory(platform, home, opts.installPath),
     checkBoot(platform, home, execImpl),
     checkUserLinger(platform, execImpl, uidVal),
     checkTmuxSurvival(platform, execImpl),
@@ -352,6 +435,8 @@ function doctor(opts = {}) {
     checkAutossh(existsImpl),
     checkSshPermitlisten(opts.sshVersion),
     checkMcpIdentity(opts.env),
+    checkTmuxServerCwd(platform, execImpl, { tmuxBin: opts.tmuxBin, procCwdImpl: opts.procCwdImpl }),
+    checkTmuxServerTermuxPreload(opts.env, execImpl, { platform, home, tmuxBin: opts.tmuxBin }),
   ];
   for (const c of checks) {
@@ -368,7 +453,9 @@ module.exports = {
   checkNode, checkTmux, checkPty, checkService, checkBoot, checkTokenPerms,
   checkMacServiceWorkingDirectory,
   checkFleetDefinitions,
+  checkServiceWorkingDirectory,
   checkTmuxSurvival, checkUserLinger,
   checkSshClient, checkAutossh, checkSshPermitlisten,
   checkMcpIdentity, checkTermuxExec,
+  checkTmuxServerCwd, checkTmuxServerTermuxPreload,
 };

package/lib/cli/service.js CHANGED Viewed

@@ -59,9 +59,12 @@ function generateService(platform, ctx) {
 function generateLinux(ctx) {
   assertSystemdSafe('repoRoot', ctx.repoRoot); // [M3] reject char non gestibili
   assertSystemdSafe('nodeBin', ctx.nodeBin);
-  const workDir = ctx.runtimeDir || path.join(ctx.home, '.nexuscrew');
-  assertSystemdSafe('runtimeDir', workDir);
-  const runtime = escapeSystemdPath(workDir);
+  // HOME is stable across init/repair/update. The runtime directory may be
+  // atomically replaced; keeping it as the service cwd leaves the HTTP process
+  // and a shared tmux server holding an orphaned inode, so every later pane can
+  // fail getcwd(3). Runtime state still lives in runtimeDir; only cwd changes.
+  assertSystemdSafe('home', ctx.home);
+  const runtime = escapeSystemdPath(ctx.home);
   const node = escapeSystemdExec(ctx.nodeBin);
   const repoBin = escapeSystemdExec(path.join(ctx.repoRoot, 'bin', 'nexuscrew.js'));
   const nodeDir = escapeSystemdPath(path.dirname(ctx.nodeBin));
@@ -151,7 +154,7 @@ export LANG=\${LANG:-en_US.UTF-8}
 export LC_CTYPE=\${LC_CTYPE:-en_US.UTF-8}
 termux-wake-lock 2>/dev/null || true
 mkdir -p "$HOME/.nexuscrew" "$TMPDIR" "$TMUX_TMPDIR"
-cd -- "$HOME/.nexuscrew"
+cd -- "$HOME"
 exec ${nodeQ} ${repoBinQ} serve --pidfile >> "$HOME/.nexuscrew/nexuscrew.log" 2>&1
 `;
 }

package/lib/diagnostics/store.js CHANGED Viewed

@@ -7,7 +7,7 @@ const ALLOWED_DURATIONS = new Set([300, 900, 1800, 3600]);
 const LEVELS = new Set(['debug', 'info', 'warn', 'error']);
 const META_KEYS = new Set([
   'port', 'platform', 'reason', 'durationSeconds', 'count', 'errno', 'client',
-  'cell', 'engine', 'action', 'state', 'transport', 'phase', 'version', 'status', 'node',
+  'cell', 'engine', 'action', 'state', 'transport', 'phase', 'version', 'status', 'node', 'code',
 ]);
 const DENIED_KEY = /(authorization|cookie|token|secret|credential|password|prompt|terminal|argv|command|env|content|payload|file|path|endpoint|url)/i;

package/lib/fleet/builtin.js CHANGED Viewed

@@ -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) {
@@ -487,6 +643,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 +653,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 +752,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 +784,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 +815,8 @@ async function createBuiltinFleet(cfg = {}) {
 module.exports = {
   createBuiltinFleet,
+  backfillShellEngine,
+  resolveCellCwd,
   composeLaunchArgv,
   composeClientInvocation,
   minimalEnv,