@mmmbuto/nexuscrew 0.8.16 → 0.8.18

package/lib/fleet/builtin.js

@@ -1,229 +1,53 @@
 'use strict';
-// B4.2 — Fleet built-in. Implementa lo STESSO contratto di lib/fleet/index.js
-// (createFleet: available / status / up / down / engine / boot / isCellSession)
-// leggendo le definizioni da ~/.nexuscrew/fleet.json tramite lib/fleet/definitions.js,
-// e lo ESTENDE con define*/edit*/remove* + schema + capabilities (design §4b/§9c).
+// B4.2 — Fleet built-in. FACADE: implementa lo STESSO contratto di
+// lib/fleet/index.js (createFleet: available / status / up / down / engine /
+// boot / isCellSession) leggendo le definizioni da ~/.nexuscrew/fleet.json
+// tramite lib/fleet/definitions.js, e lo ESTENDE con define*/edit*/remove* +
+// schema + capabilities (design §4b/§9c).
 //
-// Agnostico: non conosce "claude"/"glm"/"codex" — lancia solo command+args dichiarati.
+// La responsabilita' runtime/launch (status/up/down/restart + launch/readiness
+// helpers) e' stata estratta in modo behavior-preserving in:
+//   - lib/fleet/launch.js   toolkit stateless (argv/env/readiness/redaction)
+//   - lib/fleet/runtime.js  createBuiltinRuntime: cache + status/up/down/restart
+// Qui resta il bootstrap del cfg, l'istanziazione del runtime e il CRUD
+// (define/edit/remove, engine/boot, import, restore, schema, definitions,
+// credentials) che collabora con gli accessor del runtime. Il facade re-esporta
+// i simboli di launch.js per i test che li importano da builtin.js.
 //
-// Sicurezza (design §6 / §9a / §9d / §9e):
+// Agnostico: non conosce "claude"/"glm"/"codex" — lancia solo command+args
+// dichiarati.
+//
+// Sicurezza (design §6 / §9a / §9d / §9e) — invariata, vedi launch.js/runtime.js:
 //  - up esegue validateCommandTrust(command) e resolveCwd(cwd) PRIMA di lanciare;
 //    una cella/engine mancante o non trusted -> httpError(400), NON lancia nulla.
-//  - command/args/env NON passano per una shell: execFile + argv diretto (tmux fa
-//    exec del comando, NON sh -c — verificato: ';','|','$' passano verbatim).
-//  - env: il builtin lancia con un env MINIMALE controllato dal service (allowlist
-//    dura); engine.env — gia' ripulito dalle loader-key da parseDefinitions —
-//    raggiunge il client solo tramite un broker AF_UNIX privato e monouso. Nessun
-//    valore passa in argv, `tmux -e`, file temporanei o ambiente globale tmux.
-//    PATH lo controlla il service, mai la definizione.
+//  - command/args/env NON passano per una shell: execFile + argv diretto.
+//  - env: il builtin lancia con un env MINIMALE controllato dal service; engine.env
+//    raggiunge il client solo tramite un broker AF_UNIX privato e monouso.
 //  - READONLY (cfg.readonlyDefault===true | NEXUSCREW_READONLY=1) blocca ogni
 //    mutazione fleet e ogni up (§9d): passano solo status/schema/capabilities.
-//  - 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).
-const fs = require('node:fs');
+//  - promptMode 'send-keys' inietta via bracketed paste; se il command e' gia'
+//    uscito (sessione morta) NON digita (§9e).
 const os = require('node:os');
 const path = require('node:path');
-const { execFile } = require('node:child_process');
 const {
-  parseDefinitions, validateCommandTrust, resolveCwd,
   loadDefinitions, atomicWrite, CAPS, MAX_CELLS, validTmuxName,
 } = require('./definitions.js');
 const {
-  publicCatalog, describeManaged, resolveManagedEngine, discoverOllamaModels, discoverPiModels,
+  publicCatalog, describeManaged,
 } = require('./managed.js');
 const { validEnvKey } = require('./env-key.js');
 const { setCredential, removeCredential } = require('./credentials.js');
 const { createLaunchBroker } = require('./launch-broker.js');
-const { MINIMAL_ENV_KEYS, minimalRuntimeEnv } = require('../runtime/env.js');
-
-const STATUS_TTL_MS = 2000;
-
-// 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 { MINIMAL_ENV_KEYS } = require('../runtime/env.js');
 
-    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 */ }
-  }
-}
+// Toolkit stateless + runtime estratti (behavior-preserving). I simboli di
+// launch.js sono re-esportati in module.exports per i test che li importano
+// da builtin.js; httpError e' usato anche dal CRUD del facade.
+const { createBuiltinRuntime } = require('./runtime.js');
+const {
+  composeLaunchArgv, composeClientInvocation, minimalEnv, promptCharsOk,
+  redactSecrets, sanitizeEarlyDiagnostic, waitStablePane, httpError,
+} = require('./launch.js');
 
 // Copia deep delle definizioni per il draft di mutazione (round-trip sicuro su disco).
 function draftFrom(defs) {
@@ -272,7 +96,7 @@ function applyCellTransition(target, engineId, { model, hasModel, policy, hasPol
 // ---------------------------------------------------------------------------
 // createBuiltinFleet(cfg) — async per parita' di contratto con createFleet.
 // cfg: { fleetDefsPath?, tmuxBin?, home?, builtinEnabled?, readonlyDefault?,
-//        sendKeysReadyMs?, fleetProviderReason? }
+//        sendKeysReadyMs?, fleetProviderReason?, launchBroker?, launchReadyMs? }
 // ---------------------------------------------------------------------------
 async function createBuiltinFleet(cfg = {}) {
   const off = {
@@ -290,219 +114,32 @@ async function createBuiltinFleet(cfg = {}) {
   // Bootstrap: fleet.json valido? garbage -> unavailable (fail-closed, design §7)
   const boot = loadDefinitions(defsPath);
   if (!boot) return off;
-  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
-  }
-  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; }
-
-  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 };
-  }
+  // Runtime estratto (lib/fleet/runtime.js): possiede cache + definizioni e
+  // espone status/up/down/restart/isCellSession + gli accessor allo store
+  // (reloadDefs/findCell/findEngine/refreshSessions/commitDefs) che il CRUD
+  // qui sotto riusa. status/up/down/restart sono INVARIATI.
+  const rt = createBuiltinRuntime({
+    cfg, home, defsPath, tmuxBin, readonly, launchBroker, boot,
+  });
+  const {
+    status, up, down, restart, isCellSession,
+    reloadDefs, findCell, findEngine, refreshSessions, commitDefs,
+  } = rt;
 
-  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)}`);
+  // Scrive il draft mutato; atomicWrite valida PRIMA (fail-closed). Su input
+  // invalido: backup predecessore + throw -> httpError(400) (mai garbage).
+  async function mutate(defs, mutator) {
+    const draft = draftFrom(defs);
+    mutator(draft);
+    let parsed;
+    try {
+      parsed = atomicWrite(defsPath, draft);
+    } catch (e) {
+      throw httpError(400, `definizioni non valide: ${e.message}`);
     }
-    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);
+    commitDefs(parsed);
+    return parsed;
   }
 
   async function setEngine(cellId, engId, opts = {}) {
@@ -897,21 +534,6 @@ async function createBuiltinFleet(cfg = {}) {
     return credentialStatus();
   }
 
-  // Scrive il draft mutato; atomicWrite valida PRIMA (fail-closed). Su input
-  // invalido: backup predecessore + throw -> httpError(400) (mai garbage).
-  async function mutate(defs, mutator) {
-    const draft = draftFrom(defs);
-    mutator(draft);
-    let parsed;
-    try {
-      parsed = atomicWrite(defsPath, draft);
-    } catch (e) {
-      throw httpError(400, `definizioni non valide: ${e.message}`);
-    }
-    cache = { ...cache, at: 0, defs: parsed };
-    return parsed;
-  }
-
   // schema() — descrittore campi per editor UI schema-driven (design §5/§9f).
   function schema() {
     return {