@mmmbuto/nexuscrew 0.8.15 → 0.8.17

package/lib/fleet/launch.js

@@ -0,0 +1,227 @@
+'use strict';
+// Launch + readiness toolkit del fleet built-in (estratto da builtin.js in
+// modo behavior-preserving). Tutto cio' che sta qui e' STATELESS: ogni
+// funzione riceve le proprie dipendenze come argomento e non tocca lo stato
+// del fleet. createBuiltinRuntime() in runtime.js ne fa uso; builtin.js e'
+// ora un facade che re-esporta questi simboli per i test.
+//
+// Sicurezza (design §9a/§9e/§9h) — invariata rispetto a builtin.js:
+//  - command/args/env NON passano per una shell: execFile + argv diretto
+//    (tmux fa exec del comando, NON sh -c — verificato: ';','|','$' passano
+//    verbatim). Nessun valore passa in argv, `tmux -e`, file temporanei o
+//    ambiente globale tmux. PATH lo controlla il service, mai la definizione.
+//  - env minimale controllato dal service (allowlist dura); le definizioni non
+//    possono toccare PATH/loader-key (parseDefinitions le rifiuta gia' in env).
+//  - promptMode 'send-keys' inietta via `tmux load-buffer` + `paste-buffer -p`
+//    (bracketed paste), NON send-keys grezzo; se il command e' gia' uscito
+//    (sessione morta) NON digita (§9e).
+//  - redactSecrets/sanitizeEarlyDiagnostic (§9h): stderr/stdout dei comandi
+//    tmux falliti NON devono mai ecoare i segreti delle definizioni.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { minimalRuntimeEnv } = require('../runtime/env.js');
+
+// Env minimale controllato dal service (design §9a). Allowlist DURA: le definizioni
+// non possono toccare PATH/loader-key (parseDefinitions le rifiuta gia' in env);
+// qui NON passiamo MAI l'env del processo per intero. engine.env viene consegnato
+// direttamente al processo figlio dal broker, senza entrare nello stato tmux.
+// Nota: se un server tmux e' gia' in esecuzione (avviato fuori dal service), i comandi
+// ereditano l'env di quel server; la garanzia dura resta: le definizioni non possono
+// iniettare loader-key, e engine.env arriva al pane SOLO tramite chiavi validate.
+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; }
+
+// Marcatore di redazione (design §9h): stderr/stdout dei comandi tmux falliti
+// NON devono mai ecoare i segreti delle definizioni.
+const REDACTED = '‹redacted›';
+
+// redactSecrets(text, engine, cell) -> string con ogni occorrenza dei segreti
+// delle definizioni sostituita da '‹redacted›'. Segreti coperti (§9h):
+//  - 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
+// 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.
+function redactSecrets(text, engine, cell) {
+  if (typeof text !== 'string' || text === '') return text;
+  const secrets = [];
+  if (engine && typeof engine === 'object' && engine.env) {
+    for (const v of Object.values(engine.env)) {
+      if (typeof v === 'string' && v) secrets.push(v);
+    }
+  }
+  if (engine && typeof engine.prompt === 'string' && engine.prompt) secrets.push(engine.prompt);
+  if (cell && typeof cell.prompt === 'string' && cell.prompt) secrets.push(cell.prompt);
+  // 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);
+  let out = text;
+  for (const s of secrets) out = out.split(s).join(REDACTED); // replace globale, regex-free
+  return out;
+}
+
+const MAX_EARLY_DIAGNOSTIC = 1200;
+
+function sanitizeEarlyDiagnostic(text, engine, cell, home) {
+  let out = redactSecrets(String(text || ''), engine, cell);
+  // ANSI CSI/OSC e byte di controllo non devono arrivare nell'errore JSON/UI.
+  out = out.replace(/\x1b\][^\x07]*(?:\x07|$)/g, '')
+    .replace(/\x1b\[[0-?]*[ -\/]*[@-~]/g, '');
+  let clean = '';
+  for (let i = 0; i < out.length; i += 1) {
+    const code = out.charCodeAt(i);
+    if (code === 9 || code === 10 || code === 13 || (code >= 32 && code !== 127)) clean += out[i];
+  }
+  out = clean;
+  if (typeof home === 'string' && home) out = out.split(home).join('~');
+  out = out
+    .replace(/\bBearer\s+\S+/gi, `Bearer ${REDACTED}`)
+    .replace(/\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|AUTH)[A-Z0-9_]*)(\s*[:=]\s*)\S+/g,
+      (_m, key, sep) => `${key}${sep}${REDACTED}`)
+    .replace(/\b(?:sk|fw|fpk|hf|zai)-[A-Za-z0-9._-]{8,}\b/gi, REDACTED);
+  const lines = out.split(/\r?\n/).map((line) => line.trimEnd())
+    .filter((line) => line.trim() && !/^Pane is dead \(status /i.test(line.trim()));
+  out = lines.join('\n').trim();
+  if (out.length > MAX_EARLY_DIAGNOSTIC) out = `…${out.slice(-(MAX_EARLY_DIAGNOSTIC - 1))}`;
+  return out;
+}
+
+// Esecutore tmux: argv diretto (MAI shell). Risolve sempre {err,stdout,stderr,code}
+// cosi' il chiamante distingue "sessione assente" (code!==0 atteso) da errori reali.
+function tmuxExec(tmuxBin, args, { env, timeoutMs = 10000 } = {}) {
+  return new Promise((resolve) => {
+    execFile(tmuxBin, args, { env, timeout: timeoutMs }, (err, stdout, stderr) => {
+      const code = err && typeof err.code === 'number' ? err.code : (err ? 1 : 0);
+      resolve({ err, stdout: String(stdout || ''), stderr: String(stderr || ''), code });
+    });
+  });
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+// Policy caratteri del prompt send-keys (§9e): ammette stampabili + \t \n \r;
+// rifiuta ESC(0x1b) e gli altri byte di controllo (niente marker bracketed-paste
+// iniettabili). parseDefinitions caps solo la lunghezza: questo e' defense-in-depth.
+function promptCharsOk(prompt) {
+  if (typeof prompt !== 'string') return false;
+  for (let i = 0; i < prompt.length; i += 1) {
+    const c = prompt.charCodeAt(i);
+    if (c === 9 || c === 10 || c === 13) continue;        // \t \n \r ammessi
+    if (c < 32 || c === 127) return false;                 // ESC/null/altri control
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Build the direct child invocation separately from tmux. This lets the secure
+// launch broker carry the complete child argv and environment in memory while
+// tmux receives only the broker helper path and a one-time nonce.
+// ---------------------------------------------------------------------------
+function composeClientInvocation(engine, cell) {
+  const args = [...(engine.args || [])];
+  // model: flag + (override cella || valore engine), solo se c'e' un valore
+  if (engine.model) {
+    const val = (cell.model != null && cell.model !== '') ? cell.model : engine.model.value;
+    if (val) args.push(engine.model.flag, val);
+  }
+  // prompt flag-mode: promptFlag + prompt cella, solo se c'e' un prompt effettivo.
+  // SICUREZZA (design §9h): promptMode 'flag' mette il prompt in ARGV -> e' visibile
+  // nella process list (ps) / argv della sessione, a differenza di 'send-keys' che lo
+  // inietta DOPO via bracketed paste. Va quindi vincolato a prompt NON-segreti.
+  if (engine.promptMode === 'flag' && cell.prompt) {
+    args.push(engine.promptFlag, cell.prompt);
+  }
+  return { command: engine.command, args };
+}
+
+// composeLaunchArgv({tmuxSession, realCwd, engine, cell}) -> argv per new-session
+// PURA + testabile. Provider values are deliberately absent: no `tmux -e`, no
+// environment value and no broker payload ever appears in the tmux client argv.
+function composeLaunchArgv({ tmuxSession, realCwd, engine, cell }) {
+  const child = composeClientInvocation(engine, cell);
+  return ['new-session', '-d', '-s', tmuxSession, '-c', realCwd, child.command, ...child.args];
+}
+
+// Poll has-session entro readyMs (no delay fisso cieco). Ritorna true se la sessione
+// e' viva entro la deadline, false altrimenti (command uscito / mai partita).
+async function waitAlive(tmuxBin, session, { env, readyMs }) {
+  const deadline = Date.now() + Math.max(0, readyMs | 0);
+  for (;;) {
+    const r = await tmuxExec(tmuxBin, ['has-session', '-t', `=${session}`], { env, timeoutMs: 2000 });
+    if (!r.err) return true;
+    if (Date.now() >= deadline) return false;
+    await sleep(60);
+  }
+}
+
+async function waitStablePane(tmuxBin, target, { env, readyMs }) {
+  const deadline = Date.now() + Math.max(0, readyMs | 0);
+  for (;;) {
+    const state = await tmuxExec(tmuxBin,
+      ['display-message', '-p', '-t', target, '#{pane_dead}\t#{pane_dead_status}\t#{pane_id}'],
+      { env, timeoutMs: 2000 });
+    if (state.err) return { alive: false, status: null, target: null };
+    const [dead, rawStatus, paneId] = state.stdout.trim().split('\t');
+    if (!/^%[0-9]+$/.test(paneId || '')) return { alive: false, status: null, target: null };
+    if (dead === '1') {
+      const status = /^-?[0-9]+$/.test(rawStatus || '') ? Number(rawStatus) : null;
+      return { alive: false, status, target: paneId };
+    }
+    if (dead !== '0') return { alive: false, status: null, target: null };
+    if (Date.now() >= deadline) return { alive: true, status: null, target: paneId };
+    await sleep(60);
+  }
+}
+
+// Iniezione prompt send-keys via bracketed paste (come skills/.../nc-send):
+// load-buffer del prompt in un buffer nominato + paste-buffer -p (bracketed),
+// poi cleanup. Readiness best-effort: se la sessione non e' viva quando paste-iamo
+// (command gia' uscito) NON digita (design §9e). Ritorna {injected, reason}.
+async function injectPrompt(tmuxBin, session, prompt, { env, readyMs = 400, target, engine, cell } = {}) {
+  if (!promptCharsOk(prompt)) {
+    return { injected: false, reason: 'prompt contiene byte di controllo (rifiutato)' };
+  }
+  let tmp = null;
+  try {
+    tmp = path.join(os.tmpdir(), `.ncsend.${session}.${process.pid}.txt`);
+    fs.writeFileSync(tmp, prompt, { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+
+    const alive = await waitAlive(tmuxBin, session, { env, readyMs });
+    if (!alive) return { injected: false, reason: 'sessione non viva (command uscito?): nessuna digitazione' };
+
+    // Target esatto: pane id (%N) se disponibile, altrimenti '=sessione' (match
+    // esatto, mai prefix-match) — audit impl #5.
+    const to = target || `=${session}`;
+    await tmuxExec(tmuxBin, ['load-buffer', '-b', 'ncsend', tmp], { env });
+    const paste = await tmuxExec(tmuxBin, ['paste-buffer', '-p', '-t', to, '-b', 'ncsend'], { env });
+    if (paste.err) return { injected: false, reason: redactSecrets(`paste-buffer failed: ${paste.stderr.trim()}`, engine, cell) };
+    return { injected: true, reason: 'bracketed paste (load-buffer + paste-buffer -p)' };
+  } finally {
+    try { if (tmp) fs.unlinkSync(tmp); } catch (_) { /* best-effort */ }
+    try { await tmuxExec(tmuxBin, ['delete-buffer', '-b', 'ncsend'], { env }); } catch (_) { /* best-effort */ }
+  }
+}
+
+module.exports = {
+  REDACTED,
+  MAX_EARLY_DIAGNOSTIC,
+  httpError,
+  minimalEnv,
+  tmuxExec,
+  sleep,
+  promptCharsOk,
+  composeClientInvocation,
+  composeLaunchArgv,
+  waitAlive,
+  waitStablePane,
+  injectPrompt,
+  redactSecrets,
+  sanitizeEarlyDiagnostic,
+};

package/lib/fleet/runtime.js

@@ -0,0 +1,269 @@
+'use strict';
+// Runtime del fleet built-in (estratto da builtin.js in modo behavior-preserving).
+// Possiede lo stato condiviso (cache definizioni + sessioni tmux) ed espone:
+//   status / up / down / restart / isCellSession   — contratto runtime
+//   reloadDefs / findCell / findEngine / refreshSessions / commitDefs
+//     — accessor allo store, riusati dal facade CRUD di builtin.js
+//
+// Tutto l'argv/env/readiness/redaction e' delegato al toolkit stateless
+// launch.js. createBuiltinFleet() (builtin.js) istanzia questo runtime e
+// costruisce sopra di esso il CRUD/schema/credentials.
+//
+// Il contratto pubblico, l'argv, l'env, i readiness check, la permission
+// policy, la redazione e il testo degli errori sono INVARIATI rispetto a
+// builtin.js prima dell'estrazione.
+const path = require('node:path');
+const {
+  loadDefinitions, validateCommandTrust, resolveCwd,
+} = require('./definitions.js');
+const {
+  describeManaged, resolveManagedEngine, discoverOllamaModels, discoverPiModels,
+} = require('./managed.js');
+const {
+  httpError, minimalEnv, tmuxExec,
+  composeClientInvocation, composeLaunchArgv,
+  waitAlive, waitStablePane, injectPrompt,
+  redactSecrets, sanitizeEarlyDiagnostic,
+} = require('./launch.js');
+
+// TTL della cache status (ms): scaduto, status rilegge tmux + defs da disco.
+const STATUS_TTL_MS = 2000;
+
+function findCell(defs, id) { return defs.cells.find((c) => c.id === id) || null; }
+function findEngine(defs, id) { return defs.engines.find((e) => e.id === id) || null; }
+
+// ---------------------------------------------------------------------------
+// createBuiltinRuntime(ctx)
+//   ctx: { cfg, home, defsPath, tmuxBin, readonly, launchBroker, boot }
+//   boot = definizioni iniziali (loadDefinitions, non null: il caller gia'
+//   e' tornato unavailable su garbage).
+// ---------------------------------------------------------------------------
+function createBuiltinRuntime(ctx) {
+  const { cfg, home, defsPath, tmuxBin, readonly, launchBroker, boot } = ctx;
+  let cache = { at: 0, defs: boot, sessions: new Set() };
+
+  function reloadDefs() {
+    const d = loadDefinitions(defsPath);
+    if (d) cache = { ...cache, at: 0, defs: d };
+    return cache.defs; // mai null: boot non-null e reload mantiene l'ultimo valido
+  }
+
+  // Commit del defs mutato dal facade CRUD (builtin.js mutate()). invalida anche
+  // la TTL dello status, esattamente come faceva builtin.js prima dell'estrazione.
+  function commitDefs(defs) {
+    cache = { ...cache, at: 0, defs };
+    return defs;
+  }
+
+  async function refreshSessions() {
+    const r = await tmuxExec(tmuxBin, ['list-sessions', '-F', '#{session_name}\t#{session_windows}'], { env: minimalEnv() });
+    if (r.err) return new Set();            // nessun server / nessuna sessione
+    const set = new Set();
+    for (const line of r.stdout.split('\n')) {
+      const [rawName, rawWindows] = line.split('\t');
+      const n = String(rawName || '').trim();
+      const windows = rawWindows === undefined ? 1 : Number(rawWindows);
+      if (n && Number.isFinite(windows) && windows > 0) set.add(n);
+    }
+    return set;
+  }
+
+  async function status() {
+    if (Date.now() - cache.at > STATUS_TTL_MS) {
+      reloadDefs();                          // pick-up di edit esterne/file
+      const sessions = await refreshSessions();
+      cache = { at: Date.now(), defs: cache.defs, sessions };
+    }
+    const sessions = cache.sessions;
+    const cells = cache.defs.cells.map((c) => {
+      const alive = sessions.has(c.tmuxSession);
+      // Effective policy per cella: override remembered per-engine, altrimenti il
+      // default dell'engine gestito. Esposta SOLO come policy effettiva (mai segreti).
+      const engineDef = findEngine(cache.defs, c.engine);
+      const engineDefault = engineDef && engineDef.managed ? engineDef.managed.permissionPolicy : '';
+      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'
+        ? 'standard'
+        : (remembered || engineDefault || '');
+      return {
+        cell: c.id, tmuxSession: c.tmuxSession, engine: c.engine,
+        model: c.model || '', models: { ...(c.models || {}) },
+        permissionPolicy: effectivePolicy,
+        permissionPolicies: { ...(c.permissionPolicies || {}) },
+        active: alive, boot: c.boot, tmux: alive,
+        rc: '', key: '', degraded: false, // builtin: cella "up" <=> sessione tmux viva
+      };
+    });
+    const needsOllama = cache.defs.engines.some((e) => e.managed?.provider === 'ollama-cloud');
+    const ollamaModels = needsOllama ? await discoverOllamaModels({ ...cfg, home }) : [];
+    const needsPi = cache.defs.engines.some((e) => e.managed?.client === 'pi');
+    const piModels = needsPi ? await discoverPiModels({ ...cfg, home }) : {};
+    const engines = cache.defs.engines.map((e) => {
+      const managed = e.managed ? describeManaged(e.managed, { ...cfg, home }) : null;
+      return {
+        id: e.id, label: e.label, rc: !!e.rc,
+        ...(managed ? {
+          kind: 'managed', client: managed.client, provider: managed.provider,
+          model: e.managed.model || managed.defaultModel || '',
+          models: managed.provider === 'ollama-cloud' ? ollamaModels
+            : (managed.client === 'pi'
+              ? (e.managed.provider === 'custom'
+                ? [e.managed.model]
+                : (e.managed.provider === 'native'
+                  ? [...new Set(Object.values(piModels).flat())]
+                  : (piModels[e.managed.provider] || [])))
+              : managed.models),
+          configured: managed.configured, reason: managed.reason,
+        } : { kind: 'custom', configured: true, model: e.model?.value || '', models: [] }),
+      };
+    });
+    return {
+      available: true,
+      provider: 'builtin',
+      bootOwner: 'builtin', // §9b: la UI non puo' mentire su chi possiede il boot
+      reason: cfg.fleetProviderReason || 'fleet.json definitions',
+      cells, engines,
+    };
+  }
+
+  function isCellSession(name) {
+    return cache.defs.cells.some((c) => c.tmuxSession === String(name));
+  }
+
+  // up — ordine obbligatorio (design §9a, task B4.2).
+  // Le override {engine,boot} del contratto route sono ignorate: il builtin e'
+  // definitions-driven (l'engine della cella e' quello dichiarato; boot e' uno
+  // stato persistente gestito da boot()). Lancia SENZA shell.
+  async function up(cellId /* , { engine, boot } = {} */) {
+    if (readonly()) throw httpError(403, 'READONLY: up bloccato');
+    const defs = reloadDefs();
+    const cell = findCell(defs, cellId);
+    if (!cell) throw httpError(400, `cella sconosciuta: ${cellId}`);
+    const engine = findEngine(defs, cell.engine);
+    if (!engine) throw httpError(400, `engine dangling per cella ${cellId}: ${cell.engine}`);
+    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}`);
+      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}`);
+    // (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}`);
+
+    // (4)+(5) argv diretto (no shell). Environment-bearing launches go
+    // through a private, one-shot Unix-socket broker so credentials never
+    // appear in `ps`, tmux argv, tmux global/session env or a temporary file.
+    // '-P -F #{pane_id}': tmux stampa il pane id della sessione appena creata,
+    // cosi' l'iniezione del prompt bersaglia ESATTAMENTE quel pane (audit impl
+    // #5: elimina la race di riuso del nome sessione tra waitAlive e paste).
+    let tmuxLaunchEngine = launchEngine;
+    if (Object.keys(launchEngine.env || {}).length) {
+      const child = composeClientInvocation(launchEngine, cell);
+      const ticket = await launchBroker.issue({
+        command: child.command,
+        args: child.args,
+        env: { ...minimalEnv(), ...launchEngine.env },
+      });
+      tmuxLaunchEngine = {
+        command: process.execPath,
+        args: [path.join(__dirname, 'cell-exec.js'), '--socket', ticket.socketPath, '--nonce', ticket.nonce],
+        env: {}, promptMode: 'managed-argv',
+      };
+    }
+    const argv = composeLaunchArgv({ tmuxSession: cell.tmuxSession, realCwd, engine: tmuxLaunchEngine, cell });
+    argv.splice(2, 0, '-P', '-F', '#{pane_id}');
+    // Mantieni il pane morto solo durante la finestra di readiness: permette di
+    // catturare un errore reale del client senza lasciare una sessione fantasma.
+    // Il separatore e' interpretato da tmux (execFile argv diretto), non da shell.
+    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)
+        ? '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);
+    }
+
+    // `tmux new-session -d` can return 0 even when the launched CLI exits a
+    // moment later (missing login, bad model, incompatible provider).  Without
+    // this readiness gate the PWA reported success and then showed nothing.
+    // Always verify liveness, including cells without a system prompt.
+    const readyMs = cfg.launchReadyMs != null ? cfg.launchReadyMs : 500;
+    const paneId = launch.stdout.trim().split('\n')[0] || '';
+    const readiness = paneId.startsWith('%')
+      ? await waitStablePane(tmuxBin, paneId, { env: minimalEnv(), readyMs })
+      : { alive: await waitAlive(tmuxBin, cell.tmuxSession, { env: minimalEnv(), readyMs }), status: null, target: null };
+    if (!readiness.alive) {
+      let diagnostic = '';
+      if (readiness.target) {
+        const captured = await tmuxExec(tmuxBin,
+          ['capture-pane', '-p', '-S', '-80', '-t', readiness.target], { env: minimalEnv(), timeoutMs: 2000 });
+        if (!captured.err) diagnostic = sanitizeEarlyDiagnostic(captured.stdout, launchEngine, cell, home);
+      }
+      // remain-on-exit era soltanto diagnostico: nessun pane morto deve restare
+      // nella Fleet o nella lista tmux dopo aver raccolto l'errore.
+      await tmuxExec(tmuxBin, ['kill-session', '-t', `=${cell.tmuxSession}`], { env: minimalEnv(), timeoutMs: 2000 });
+      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'}`);
+    }
+    if (readiness.target) {
+      await tmuxExec(tmuxBin,
+        ['set-option', '-w', '-t', readiness.target, 'remain-on-exit', 'off'], { env: minimalEnv(), timeoutMs: 2000 });
+    }
+
+    // (6) prompt send-keys: bracketed-paste best-effort, target = pane id esatto
+    // (fallback al nome sessione con match esatto '=' se tmux non ha stampato l'id).
+    let prompt = null;
+    if (launchEngine.promptMode === 'send-keys' && cell.prompt) {
+      const target = paneId.startsWith('%') ? paneId : `=${cell.tmuxSession}`;
+      prompt = await injectPrompt(tmuxBin, cell.tmuxSession, cell.prompt, {
+        env: minimalEnv(),
+        readyMs: cfg.sendKeysReadyMs != null ? cfg.sendKeysReadyMs : readyMs,
+        target,
+        engine: launchEngine, cell, // per la redazione del reason se paste-buffer fallisce (§9h)
+      });
+    }
+    cache = { ...cache, at: 0 };              // invalida: prossimo status rilegge tmux
+    return { ok: true, cell: cellId, session: cell.tmuxSession, prompt };
+  }
+
+  async function down(cellId /* , opts */) {
+    if (readonly()) throw httpError(403, 'READONLY: down bloccato');
+    const defs = reloadDefs();
+    const cell = findCell(defs, cellId);
+    if (!cell) throw httpError(400, `cella sconosciuta: ${cellId}`);
+    const engine = findEngine(defs, cell.engine) || {};
+    const r = await tmuxExec(tmuxBin, ['kill-session', '-t', `=${cell.tmuxSession}`], { env: minimalEnv() });
+    if (r.err && !/no server running|can't find session|not found/i.test(r.stderr)) {
+      throw httpError(500, `tmux kill-session failed: ${redactSecrets(r.stderr.trim(), engine, cell)}`);
+    }
+    cache = { ...cache, at: 0 };
+    return { ok: true, killed: !r.err };
+  }
+
+  // restart = down (riusa la kill esistente; sessione non viva NON e' errore,
+  // come down) seguito da up (rilancia secondo la definizione corrente).
+  // Capability del SOLO built-in: i provider legacy non la espongono (501 in route).
+  async function restart(cellId) {
+    if (readonly()) throw httpError(403, 'READONLY: restart bloccato');
+    await down(cellId); // idempotente: cella non viva -> nessun errore
+    return up(cellId);
+  }
+
+  return {
+    status, up, down, restart, isCellSession,
+    reloadDefs, findCell, findEngine, refreshSessions, commitDefs,
+  };
+}
+
+module.exports = { createBuiltinRuntime, findCell, findEngine, STATUS_TTL_MS };

package/lib/mcp/cells.js

@@ -0,0 +1,154 @@
+'use strict';
+// Helper cella/deck/topologia per il server MCP (`lib/mcp/server.js`).
+//
+// Cohesione di tutto cio' che legge la directory delle celle Fleet e risolve
+// owner/route/topologia: layout deck (ordine visuale), normalizzazione payload
+// celle, parsing del target owner-qualified, costruzione della route federata
+// e della directory aggregata locale+remota. Queste funzioni parlano SOLO via
+// l'astrazione `ctx.api` (loopback + Bearer del bridge); ACL e identita'
+// owner-qualified sono applicate lato server HTTP.
+const { isValidSession } = require('../files/store.js');
+
+const NODE_PART_RE = /^[a-z0-9-]{1,32}$/;
+const NODE_ID_RE = /^[a-f0-9]{16,64}$/;
+const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
+
+// Deck layout is stored column-major, while the UI is read row-major. Preserve
+// the visual order so an agent sees the same neighbourhood as the operator.
+function orderedDeckMembers(deck) {
+  const columns = deck && deck.layout && Array.isArray(deck.layout.columns)
+    ? deck.layout.columns : [];
+  const rows = Math.max(0, ...columns.map((column) => (
+    column && Array.isArray(column.tiles) ? column.tiles.length : 0
+  )));
+  const out = [];
+  for (let row = 0; row < rows; row += 1) {
+    for (const column of columns) {
+      const tile = column && Array.isArray(column.tiles) ? column.tiles[row] : null;
+      if (!tile || typeof tile.session !== 'string' || !tile.session) continue;
+      const member = { tmuxSession: tile.session };
+      if (typeof tile.node === 'string' && tile.node) member.node = tile.node;
+      if (typeof tile.ownerId === 'string' && NODE_ID_RE.test(tile.ownerId)) member.ownerId = tile.ownerId;
+      out.push(member);
+    }
+  }
+  return out;
+}
+
+function fleetStatusPath(node) {
+  if (!node) return '/api/fleet/status';
+  const parts = String(node).split('/');
+  if (!parts.length || parts.some((part) => !NODE_PART_RE.test(part))
+    || new Set(parts).size !== parts.length) return null;
+  return `/api/route/${parts.map(encodeURIComponent).join('/')}/_/fleet/status`;
+}
+
+function fleetCellsBySession(payload) {
+  const out = new Map();
+  if (!payload || payload.available !== true || !Array.isArray(payload.cells)) return out;
+  for (const cell of payload.cells) {
+    if (!cell || typeof cell.tmuxSession !== 'string' || !cell.tmuxSession
+      || typeof cell.cell !== 'string' || !cell.cell) continue;
+    out.set(cell.tmuxSession, cell.cell);
+  }
+  return out;
+}
+
+function routePath(route, resource) {
+  if (!Array.isArray(route) || !route.length || route.length > 4
+    || route.some((part) => !NODE_PART_RE.test(part)) || new Set(route).size !== route.length) return null;
+  return `/api/route/${route.map(encodeURIComponent).join('/')}/_/${resource}`;
+}
+
+function topologyOwners(payload) {
+  const out = [];
+  const seen = new Set();
+  for (const node of (payload && Array.isArray(payload.nodes) ? payload.nodes : [])) {
+    if (!node || !NODE_ID_RE.test(String(node.instanceId || '')) || seen.has(node.instanceId)
+      || !Array.isArray(node.route) || !routePath(node.route, 'decks')) continue;
+    seen.add(node.instanceId);
+    out.push({
+      instanceId: node.instanceId,
+      route: [...node.route],
+      label: typeof node.label === 'string' && node.label ? node.label : (node.name || node.route.join(' › ')),
+      stale: node.stale === true,
+    });
+  }
+  return out;
+}
+
+function memberOwnerId(member, deckOwner, ownerTopology) {
+  if (member.ownerId && NODE_ID_RE.test(member.ownerId)) return member.ownerId;
+  if (!member.node) return deckOwner.instanceId;
+  const found = ownerTopology.find((node) => Array.isArray(node.route) && node.route.join('/') === member.node);
+  return found ? found.instanceId : null;
+}
+
+function parseCellTarget(value) {
+  if (typeof value !== 'string') return null;
+  const split = value.indexOf(':');
+  if (split < 16) return null;
+  const instanceId = value.slice(0, split);
+  const cell = value.slice(split + 1);
+  return NODE_ID_RE.test(instanceId) && CELL_ID_RE.test(cell) ? { instanceId, cell } : null;
+}
+
+function normalizeCellPayload(payload, owner, callerSession = null) {
+  if (!payload || payload.instanceId !== owner.instanceId || !Array.isArray(payload.cells)) return [];
+  const route = owner.route.length ? owner.route.join('/') : 'local';
+  const seen = new Set();
+  const out = [];
+  for (const raw of payload.cells) {
+    if (!raw || raw.instanceId !== owner.instanceId || !CELL_ID_RE.test(String(raw.cell || ''))
+      || typeof raw.tmuxSession !== 'string' || !isValidSession(raw.tmuxSession)
+      || seen.has(raw.cell)) continue;
+    seen.add(raw.cell);
+    out.push({
+      id: `${owner.instanceId}:${raw.cell}`,
+      instanceId: owner.instanceId,
+      owner: owner.label,
+      route,
+      cell: raw.cell,
+      tmuxSession: raw.tmuxSession,
+      engine: typeof raw.engine === 'string' ? raw.engine : '',
+      model: typeof raw.model === 'string' ? raw.model : '',
+      active: raw.active === true,
+      canReceive: raw.canReceive === true,
+      lastSeen: Number.isFinite(raw.lastSeen) ? raw.lastSeen : null,
+      self: owner.route.length === 0 && callerSession === raw.tmuxSession,
+    });
+  }
+  return out;
+}
+
+async function readCellDirectory(ctx, callerSession = null) {
+  const [config, topology] = await Promise.all([
+    ctx.api('GET', '/api/config'), ctx.api('GET', '/api/topology'),
+  ]);
+  const localId = String(config && config.instanceId || '');
+  if (!NODE_ID_RE.test(localId)) throw new Error('instanceId locale non disponibile');
+  const owners = [{ instanceId: localId, route: [], label: 'Local', stale: false },
+    ...topologyOwners(topology).filter((owner) => !owner.stale && owner.instanceId !== localId)];
+  const cells = [];
+  const unavailable = [];
+  await Promise.all(owners.map(async (owner) => {
+    const apiPath = owner.route.length ? routePath(owner.route, 'cells') : '/api/cells';
+    if (!apiPath) return;
+    try {
+      cells.push(...normalizeCellPayload(await ctx.api('GET', apiPath), owner, callerSession));
+    } catch (_) {
+      unavailable.push({ instanceId: owner.instanceId, owner: owner.label,
+        route: owner.route.length ? owner.route.join('/') : 'local' });
+    }
+  }));
+  cells.sort((a, b) => (a.route === 'local' ? -1 : b.route === 'local' ? 1
+    : a.route.localeCompare(b.route)) || a.cell.localeCompare(b.cell));
+  unavailable.sort((a, b) => a.route.localeCompare(b.route));
+  return { nodeId: localId, cells, unavailable };
+}
+
+module.exports = {
+  NODE_PART_RE, NODE_ID_RE, CELL_ID_RE,
+  orderedDeckMembers, fleetStatusPath, fleetCellsBySession, routePath,
+  topologyOwners, memberOwnerId, parseCellTarget, normalizeCellPayload, readCellDirectory,
+};