@mmmbuto/nexuscrew 0.9.77 → 0.9.78

package/lib/fleet/routes.js

@@ -61,9 +61,18 @@ function fleetRoutes(fleetP, cfg = {}) {
       res.json(result);
     } catch (e) {
       if (opts.action) {
+        // Esito incerto della rotazione di sessione: un enum chiuso, mai un
+        // testo libero. Vale solo se la richiesta e' stata CONSUMATA e il
+        // lancio e' fallito dopo: il fatto che il marcatore e' consumato
+        // senza che l'esito sia tracciato, dichiarato dove si legge. Il
+        // marker e' lo STESSO in ogni ramo diagnostico di un lancio
+        // fallito: un fallimento che nasce nello spawn non e' un caso in
+        // cui il consumo diventa invisibile.
+        const consumption = e && e.vlNewSessionOutcome ? { newSession: e.vlNewSessionOutcome } : {};
         const match = String(e && e.message || '').match(/cell spawn failed:\s+([A-Z][A-Z0-9_]{0,31})\s+([A-Za-z0-9._+-]{1,128})/);
         if (match) emit('error', 'CELL_SPAWN_FAILED', 'Cell client spawn failed', {
           action: opts.action, cell: safeCell(req.body), errno: match[1], client: match[2], status: e.status || 500,
+          ...consumption,
         });
         else emit('warn', 'FLEET_ACTION_FAILED', 'Fleet action failed', {
           action: opts.action, cell: safeCell(req.body), state: 'failed',
@@ -73,6 +82,7 @@ function fleetRoutes(fleetP, cfg = {}) {
           // argv, env, prompt, token or credential ever enters here. Untagged /
           // legacy errors degrade to the bounded UNKNOWN fallback.
           code: codeOf(e.fleetCode), phase: phaseOf(e.fleetPhase),
+          ...consumption,
         });
       }
       res.status(e.status || 500).json({
@@ -138,6 +148,35 @@ function fleetRoutes(fleetP, cfg = {}) {
     return f.down(cell, { boot: !!b.boot });
   }, { mutate: true, action: 'down' }));
   r.post('/restart', guard((f, b) => { requireCap(f, 'restart'); return f.restart(String(b.cell || '')); }, { mutate: true, action: 'restart' }));
+  // Sessione nuova esplicita (vl): crea la richiesta persistente consumabile
+  // UNA volta dal prossimo lancio. Azione separata dal ciclo di lancio (nessun
+  // avvio implicito, nessun flag dell'engine): muta lo stato delle richieste,
+  // quindi e' gated da READONLY come le altre mutazioni. Senza `action:` perche'
+  // non avvia né ferma nulla — i diagnostic FLEET_ACTION_* descrivono
+  // transizioni di stato della cella, e qui la cella non cambia stato.
+  r.post('/vl-new-session', guard((f, b) => {
+    if (typeof f.vlNewSession !== 'function') { const e = new Error('not supported by this fleet provider'); e.status = 501; throw e; }
+    return f.vlNewSession(String(b.cell || ''));
+  }, { mutate: true }));
+  // Stato della richiesta di sessione nuova (read-only, per cella): il posto
+  // dove si vede che una richiesta e' stata CONSUMATA e l'esito non e'
+  // tracciato — senza creare una nuova richiesta, che sarebbe un'altra
+  // mutazione e un'altra rotazione possibile. Non e' gated da READONLY perche'
+  // non muta nulla, e il bersaglio e' dichiarato (scope-guard), quindi la
+  // risposta non porta lo stato di una cella fuori scope.
+  r.get('/vl-new-session-state', guard((f, _b, req) => {
+    if (typeof f.vlNewSessionState !== 'function') { const e = new Error('not supported by this fleet provider'); e.status = 501; throw e; }
+    const q = (req && req.query) || {};
+    return f.vlNewSessionState(String(q.cell || ''));
+  }));
+  // Inventario legacy vl (read-only): elenca le cartelle di stato condivise
+  // pre-contratto con le sessioni trovate. Diagnosi locale: niente migrazione,
+  // niente spostamenti, niente cancellazioni — mai gated da READONLY perche'
+  // non muta nulla.
+  r.get('/vl-legacy-inventory', guard((f) => {
+    if (typeof f.vlLegacyInventory !== 'function') { const e = new Error('not supported by this fleet provider'); e.status = 501; throw e; }
+    return f.vlLegacyInventory();
+  }));
   r.post('/engine', guard((f, b) => {
     const opts = { model: typeof b.model === 'string' ? b.model : '' };
     if (typeof b.permissionPolicy === 'string') opts.permissionPolicy = b.permissionPolicy;

package/lib/fleet/runtime.js

@@ -31,6 +31,7 @@ const {
   redactSecrets, sanitizeEarlyDiagnostic,
 } = require('./launch.js');
 const { waitDeliveryReport, actionRequiredFor, vlPaneReadiness } = require('./prompt-delivery.js');
+const { consumeVlNewSession, vlNewSessionStatus } = require('./vl-session.js');
 
 // Insieme MCP MATERIALIZZATO della cella — le chiavi del file che
 // writeCellMcpConfig (managed.js) scrive PRIMA dello spawn. Un server non
@@ -84,6 +85,19 @@ function buildMcpReadinessPayload(cell, realCwd, home, cfg) {
 // TTL della cache status (ms): scaduto, status rilegge tmux + defs da disco.
 const STATUS_TTL_MS = 2000;
 
+// Pausa minima fra due lanci della STESSA cella vl (ms). Il default è i 10 s
+// del contratto; configurabile via cfg.vlLaunchCooldownMs (0 lo disattiva,
+// il tetto alto è 1 h). Il clock è il MONOTONO (seam cfg.monotonicNow nei test):
+// un balzo dell'orologio di parete non accorcia la pausa minima.
+const VL_LAUNCH_COOLDOWN_DEFAULT_MS = 10000;
+const VL_LAUNCH_COOLDOWN_MAX_MS = 3600000;
+
+function clampCooldown(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n)) return VL_LAUNCH_COOLDOWN_DEFAULT_MS;
+  return Math.max(0, Math.min(VL_LAUNCH_COOLDOWN_MAX_MS, Math.floor(n)));
+}
+
 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; }
 
@@ -118,6 +132,28 @@ function createBuiltinRuntime(ctx) {
   const identityDaemonBootId = cfg.identityDaemonBootId || crypto.randomBytes(16).toString('hex');
   let cache = { at: 0, defs: boot, sessions: new Set() };
 
+  // --- Serializzazione dei lanci per cella (contratto vl, generale) ----------
+  // Due up() concorrenti della STESSA cella si serializzano su una catena di
+  // promise: il secondo vede lo stato lasciato dal primo (sessione viva ->
+  // 409 di preflight) invece di correre contro di lui sulla new-session. Il
+  // 409 resta la rete finale; il lock toglie la corsa. Celle diverse non si
+  // toccano. La mappa vive nel runtime (per processo): i nodi non condividono
+  // lanci, quindi non c'è niente da coordinare fuori processo.
+  const launchLocks = new Map();
+  // Timestamp (seam cfg.now) dell'ultimo lancio PER CELLA vl: base della
+  // pausa minima fra due lanci della stessa cella.
+  const vlLastLaunchAt = new Map();
+  const nowMs = () => (typeof cfg.now === 'function' ? cfg.now() : Date.now());
+
+  // Il clock del cooldown e' MONOTONO, mai l'orologio di parete: un balzo
+  // dell'ora (NTP, correzione manuale) non puo' accorciare la pausa minima
+  // fra due lanci della stessa cella, e non puo' nemmeno allungarla. Il
+  // default e' il clock monotono del processo; il seam `cfg.monotonicNow`
+  // serve ai test, che cosi' non dormono mai.
+  const cooldownNow = () => (typeof cfg.monotonicNow === 'function'
+    ? cfg.monotonicNow()
+    : Number(process.hrtime.bigint() / 1000000n));
+
   function reloadDefs() {
     const d = loadDefinitions(defsPath);
     if (d) cache = { ...cache, at: 0, defs: d };
@@ -199,6 +235,11 @@ function createBuiltinRuntime(ctx) {
       // if nel frontend. Solo la chiave esplicita comanda: qui non si
       // interroga mai docker (percorso caldo a polling).
       const panelUrl = aiDesktop.pubblicaPanelUrlCaldo(c.panelUrl || engineDef?.panelUrl || '');
+      // Le celle vl portano con se' lo stato della richiesta di sessione nuova:
+      // e' l'unico posto dove l'esito di un consumo si vede senza creare una
+      // NUOVA richiesta (che sarebbe un'altra mutazione). Nomi e timestamp
+      // del marcatore: nessun contenuto di sessione, mai.
+      const isVl = !!(engineDef && engineDef.managed && engineDef.managed.client === 'vl');
       return {
         // `cell` resta l'id: e' la chiave di indirizzamento. `label` e' il nome
         // leggibile e viaggia accanto, senza mai sostituirlo.
@@ -224,6 +265,7 @@ function createBuiltinRuntime(ctx) {
           : 'unavailable',
         rc: '', key: '', degraded: false, // supervisor vivo <=> sessione tmux viva
         panelUrl,
+        ...(isVl ? { newSession: vlNewSessionStatus({ home, cellId: c.id }) } : {}),
       };
     });
     return {
@@ -302,8 +344,53 @@ function createBuiltinRuntime(ctx) {
   // 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.
+  //
+  // Il corpo vero vive in upSerializzato; up() e' il lock per cella: due
+  // richieste concorrenti della stessa cella si mettono in fila (la seconda
+  // parte DOPO la prima, non accanto) e la coda si svuota da se'.
   async function up(cellId /* , { engine, boot } = {} */) {
     if (readonly()) throw httpError(403, 'READONLY: up bloccato');
+    const previous = launchLocks.get(cellId) || Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => { release = resolve; });
+    const chained = previous.then(() => gate);
+    launchLocks.set(cellId, chained);
+    try {
+      await previous;
+      return await upSerializzato(cellId);
+    } catch (e) {
+      throw annotaEsitoSessioneNuova(e, cellId);
+    } finally {
+      release();
+      if (launchLocks.get(cellId) === chained) launchLocks.delete(cellId);
+    }
+  }
+
+  // Il consumo del marcatore «sessione nuova» e' un FATTO che il solo
+  // errore di lancio non racconta: se il fallimento arriva DOPO il consumo,
+  // la richiesta e' stata consumata e l'esito vero (la sessione e' ruotata o
+  // no) NON e' tracciato da nessuna parte. Il rilievo e' che per sapere questo
+  // si doveva creare una NUOVA richiesta — cioe' un'altra mutazione, e una
+  // rotazione in piu'. Qui l'errore dichiara l'esito incerto: si sa che il
+  // consumo c'e' stato, e non si finge che la rotazione sia avvenuta. La
+  // richiesta consumata non viene MAI ripetuta in automatico.
+  function annotaEsitoSessioneNuova(e, cellId) {
+    try {
+      const st = vlNewSessionStatus({ home, cellId });
+      if (!st || st.state !== 'consumed') return e;
+      if (e && typeof e === 'object') {
+        e.data = { ...(e.data || {}), vlNewSession: st };
+        // Marker BOUNDED per i diagnostici: un enum, mai un testo libero.
+        e.vlNewSessionOutcome = 'consumed-unknown';
+      }
+    } catch (_) {
+      // Lo stato del marcatore non e' un errore: l'errore vero resta quello
+      // del lancio, e non si maschera con una lettura fallita.
+    }
+    return e;
+  }
+
+  async function upSerializzato(cellId /* , { engine, boot } = {} */) {
     if (typeof ensureProtection === 'function') await ensureProtection();
     const defs = reloadDefs();
     const cell = findCell(defs, cellId);
@@ -329,6 +416,21 @@ function createBuiltinRuntime(ctx) {
       throw httpError(409, 'sessione già in esecuzione', null,
         { phase: 'preflight', code: 'SESSION_DUPLICATE' });
     }
+    // Pausa minima fra due lanci della STESSA cella vl (contratto vl): il
+    // cooldown deduplica doppio click/retry e mette un passo massimo alla
+    // ripetizione dei lanci. Il rifiuto è dichiarato (429), mai un'attesa
+    // silenziosa dentro la route. Le celle non-vl non sono toccate; il clock
+    // è il seam cfg.now, i test non dormono.
+    if (engine.managed && engine.managed.client === 'vl') {
+      const cooldownMs = clampCooldown(cfg.vlLaunchCooldownMs !== undefined
+        ? cfg.vlLaunchCooldownMs : VL_LAUNCH_COOLDOWN_DEFAULT_MS);
+      const last = vlLastLaunchAt.get(cellId);
+      if (cooldownMs > 0 && typeof last === 'number' && cooldownNow() - last < cooldownMs) {
+        throw httpError(429,
+          `pausa minima fra due lanci della stessa cella vl non trascorsa (${cooldownMs} ms)`,
+          null, { phase: 'preflight', code: 'VL_LAUNCH_COOLDOWN' });
+      }
+    }
     let launchEngine = engine;
     // Canale di attivita' della cella: `resolved` vive solo dentro il ramo
     // managed, e il payload del broker si costruisce FUORI. Portarlo fuori con
@@ -336,6 +438,15 @@ function createBuiltinRuntime(ctx) {
     // dichiarato in un altro: un errore che in produzione fa fallire il lancio
     // di ogni cella, non una sola asserzione.
     let activityCanale = null;
+    // Sessione NUOVA esplicita (contratto vl): il marcatore persistente si
+    // consuma qui, atomicamente (rename), PRIMA dello spawn — e una volta
+    // sola. Il payload porta la decisione gia' presa (vlNewSession): il
+    // supervisore applica --new SOLO alla generazione 0, quindi un suo retry
+    // non ripete la rotazione; un restart ordinario non consuma nulla perche'
+    // il marcatore non c'e' piu'. Se il lancio fallisce dopo il consumo, il
+    // record .consumed resta a dichiarare l'esito incerto: mai un secondo
+    // --new automatico.
+    let vlNewSessionApplied = false;
     if (engine.managed) {
       // Generazione del lancio: identifica QUESTA partenza della cella. Uno
       // stato di attivita' che ne porta un'altra appartiene a un lancio
@@ -346,6 +457,10 @@ function createBuiltinRuntime(ctx) {
         ...cfg, home, extraModels: extraModelsFrom(defs),
         capabilityProfiles: defs.capabilityProfiles || null,
         activityGeneration: generazione,
+        // Stable owner identity for per-cell vl directories: resolved on THIS
+        // node (executor), never from a federated viewer.
+        vlOwnerInstanceId: typeof identityOwnerInstanceId === 'function'
+          ? identityOwnerInstanceId() : identityOwnerInstanceId,
         // La generazione NON si scrive qui: viaggia negli argv degli hook e nel
         // payload del broker, e a scriverla su disco e' `cell-exec`, dentro la
         // sessione che tmux ha appena creato — quindi solo per chi vince la
@@ -386,6 +501,20 @@ function createBuiltinRuntime(ctx) {
         throw httpError(refusal.status, refusal.message, null,
           { phase: 'preflight', code: refusal.code });
       }
+      // Consumo del marcatore «sessione nuova» (solo celle vl): superati i
+      // gate di risoluzione, prima del ticket e dello spawn. Un fallimento a
+      // valle lascia il record .consumed: l'esito incerto si RIFERISCE, non
+      // si ripete. Un albero di stato ostile e' un rifiuto dichiarato, non un
+      // lancio senza rotazione richiesta.
+      if (engine.managed.client === 'vl') {
+        try {
+          const consumed = consumeVlNewSession({ home, cellId: cell.id, now: nowMs() });
+          if (consumed.consumed) vlNewSessionApplied = true;
+        } catch (e) {
+          throw httpError(500, `richiesta sessione nuova non consumabile in sicurezza: ${e.message}`,
+            null, { phase: 'preflight', code: 'VL_NEW_SESSION_UNSAFE' });
+        }
+      }
     }
 
     // (2) trust del command PRIMA di lanciare
@@ -404,6 +533,13 @@ function createBuiltinRuntime(ctx) {
     const readyMs = cfg.launchReadyMs != null ? cfg.launchReadyMs : 500;
     const child = composeClientInvocation(launchEngine, cell);
     let ticket;
+    // Punto di impegno del lancio (celle vl): da qui in poi il lancio parte,
+    // quindi la pausa minima conta DA ORA. Un fallimento a valle (broker,
+    // tmux, readiness) lascia il timestamp: il retry riparte al passo del
+    // cooldown, non a raffica — backoff limitato, mai attese arbitrarie.
+    if (engine.managed && engine.managed.client === 'vl') {
+      vlLastLaunchAt.set(cellId, cooldownNow());
+    }
     try {
       let leaseInfo = null;
     if (leaseManager) {
@@ -448,6 +584,12 @@ function createBuiltinRuntime(ctx) {
         // iniettati (`activityDir` lo dice): senza canale non c'e' niente da
         // invalidare.
         ...(activityCanale ? { activity: activityCanale } : {}),
+        // Sessione nuova esplicita (vl): la decisione viaggia GIÀ PRESA nel
+        // payload, il supervisore non la ricalcola e non rilegge mai il
+        // marcatore. cell-exec applica --new SOLO alla generazione 0: i suoi
+        // restart usano argv senza --new, quindi la rotazione avviene una
+        // volta sola per richiesta.
+        ...(vlNewSessionApplied ? { vlNewSession: true } : {}),
         supervise: {
           enabled: !launchEngine.shellOneShot,
           initialReadyMs: Math.max(50, Math.min(30000, Number(readyMs) || 500)),
@@ -759,6 +901,8 @@ function createBuiltinRuntime(ctx) {
       // unwritable file). Strict boolean like readinessDegraded: the
       // payload may come from a federated node and the text is local i18n.
       ...(launchEngine.vlPromptDegraded ? { vlPromptDegraded: true } : {}),
+      // Sessione nuova esplicita applicata a QUESTO lancio (generazione 0).
+      ...(vlNewSessionApplied ? { vlNewSession: true } : {}),
     };
   }
 

package/lib/fleet/vl-session.js

@@ -0,0 +1,230 @@
+'use strict';
+// Explicit "new session" requests for vl cells, plus the read-only legacy
+// state inventory. Two separate contracts live here because both are pure
+// filesystem concerns of the vl engine family and neither belongs to the
+// managed-spec resolution (managed.js) or the launch cycle (runtime.js):
+//
+//  - NEW SESSION: an explicit operator action writes a PERSISTENT marker
+//    under the NexusCrew state tree. The launch cycle (runtime.up) consumes
+//    it ATOMICALLY (rename) before the spawn, exactly once: an ordinary
+//    start/restart never rotates the session, and a supervisor retry cannot
+//    repeat a rotation that already happened. If the outcome is uncertain
+//    (crash between consumption and spawn), the consumed record stays on
+//    disk and reports its state — a second automatic rotation never happens.
+//
+//  - LEGACY INVENTORY: the pre-contract vl cells shared a handful of
+//    state directories (~/.local/state/vl*). Migration is an explicit,
+//    operator-driven procedure (nothing moves or gets deleted here, ever):
+//    this only LISTS what exists so the operator can decide with data.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { safePrivateDir } = require('./credentials.js');
+
+// Same self-defense as writeVlCellPrompt (managed.js): the cell id is already
+// validated upstream (CELL_ID_RE, definitions.js), but '.' and '..' pass that
+// RE and, as a FILE NAME, they are traversal. The refusal happens before any
+// disk access.
+function assertSafeCellId(cellId) {
+  const id = typeof cellId === 'string' ? cellId : '';
+  if (!id || id === '.' || id === '..' || id.includes('/') || /[\x00-\x1f\x7f]/.test(id)) {
+    throw new Error('unsafe vl cell id');
+  }
+  return id;
+}
+
+function vlNewSessionDir(home) {
+  const nexus = path.join(home, '.nexuscrew');
+  safePrivateDir(nexus, { create: true });
+  const dir = path.join(nexus, 'vl-new-session');
+  safePrivateDir(dir, { create: true });
+  return dir;
+}
+
+function markerPaths(home, cellId) {
+  const id = assertSafeCellId(cellId);
+  const dir = vlNewSessionDir(home);
+  return { dir, requested: path.join(dir, `${id}.requested`), consumed: path.join(dir, `${id}.consumed`) };
+}
+
+// I percorsi dei marcatori per una LETTURA: nessuna directory viene creata.
+// La vista dello stato e' read-only per contratto, e una lettura che lascia
+// una directory sul disco non e' una lettura. La richiesta e il consumo
+// scrivono, e quelli passano da `markerPaths`.
+function markerPathsReadOnly(home, cellId) {
+  const id = assertSafeCellId(cellId);
+  const dir = path.join(home, '.nexuscrew', 'vl-new-session');
+  return { dir, requested: path.join(dir, `${id}.requested`), consumed: path.join(dir, `${id}.consumed`) };
+}
+
+// Atomic JSON write (tmp + fsync + rename, mode 0600) — same shape as the vl
+// catalog copy. Never a secret: the record carries ids and timestamps only.
+function writeRecordAtomic(target, record) {
+  const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(tmp, 'wx', 0o600);
+    fs.writeFileSync(fd, JSON.stringify(record));
+    fs.fsyncSync(fd);
+    fs.closeSync(fd); fd = undefined;
+    fs.renameSync(tmp, target);
+  } catch (e) {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch (_) {} }
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw e;
+  }
+}
+
+function readRecord(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch (_) { return null; }
+}
+
+// Request a fresh session for a vl cell (explicit operator action, owner
+// node). Idempotent on a pending request: a double click or a UI retry finds
+// the SAME pending marker instead of stacking a second one — the request is
+// consumable once, so there is nothing a second click could add.
+function requestVlNewSession({ home, cellId, now = Date.now() }) {
+  const { requested, consumed } = markerPaths(home, cellId);
+  const pending = readRecord(requested);
+  if (pending) {
+    return { state: 'pending', requestedAt: pending.requestedAt || 0, alreadyPending: true };
+  }
+  const previous = readRecord(consumed);
+  writeRecordAtomic(requested, { cell: cellId, requestedAt: now });
+  return {
+    state: 'pending',
+    requestedAt: now,
+    alreadyPending: false,
+    // The last consumption, if any: with a pending request on top of it this
+    // is also how an "outcome unknown" previous rotation surfaces.
+    ...(previous ? { lastConsumedAt: previous.consumedAt || 0 } : {}),
+  };
+}
+
+// Consume the pending request ATOMICALLY, before the spawn. The rename IS the
+// consumption: two consumers cannot both win, and a crash before the rename
+// leaves the request pending (the launch never happened, the rotation never
+// happened — the next launch may consume it). `consumedAt` is stamped just
+// before the rename: a crash between the stamp and the rename keeps the
+// request pending with a slightly early timestamp, which is harmless — the
+// record still tells the truth about WHAT happened, never invents a rotation.
+function consumeVlNewSession({ home, cellId, now = Date.now() }) {
+  const { requested, consumed } = markerPaths(home, cellId);
+  const pending = readRecord(requested);
+  if (!pending) return { consumed: false };
+  writeRecordAtomic(requested, { cell: cellId, requestedAt: pending.requestedAt || 0, consumedAt: now });
+  fs.renameSync(requested, consumed);
+  return { consumed: true, requestedAt: pending.requestedAt || 0, consumedAt: now };
+}
+
+// Current state of the request, for diagnostics and for reporting an
+// uncertain outcome: 'pending' means the next launch will rotate; 'consumed'
+// means a launch consumed the request — whether the runtime actually rotated
+// is NOT tracked here (NexusCrew never reads vl session content), and that is
+// exactly what the state says, instead of guessing.
+function vlNewSessionStatus({ home, cellId }) {
+  const { requested, consumed } = markerPathsReadOnly(home, cellId);
+  const pending = readRecord(requested);
+  if (pending) {
+    const last = readRecord(consumed);
+    return {
+      state: 'pending',
+      requestedAt: pending.requestedAt || 0,
+      ...(last ? { lastConsumedAt: last.consumedAt || 0 } : {}),
+    };
+  }
+  const done = readRecord(consumed);
+  if (done) {
+    return {
+      state: 'consumed',
+      requestedAt: done.requestedAt || 0,
+      consumedAt: done.consumedAt || 0,
+      outcome: 'not-tracked',
+    };
+  }
+  return { state: 'none' };
+}
+
+// --- Legacy inventory (read-only) -------------------------------------------
+//
+// The shared pre-contract state directories: `~/.local/state/vl` and every
+// `vl-*` sibling directory. Sessions live at
+// `<dir>/vl/host-v1/sessions/<name>` (measured on the live tree). The new
+// per-cell layout lives under ~/.nexuscrew/vl-cells and never matches this
+// scan, so what this lists is legacy shared state by construction.
+// Names only, never content: a session transcript stays with vl.
+const LEGACY_SESSIONS_REL = path.join('vl', 'host-v1', 'sessions');
+const LEGACY_SESSIONS_CAP = 64;
+
+// True se un componente del percorso (a partire da `base`) e' un symlink.
+// L'inventario legacy deve restare dentro l'albero dello stato: un symlink
+// INTERMEDIO (per esempio `vl/host-v1` che punta altrove) porterebbe la
+// scansione a elencare le sessioni di un albero esterno. Il controllo
+// guardava solo la directory finale e il path terminale: i componenti in
+// mezzo restavano fuori dal controllo.
+function hasSymlinkComponent(base, target) {
+  const rel = path.relative(base, target);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return true;
+  let cur = base;
+  for (const part of rel.split(path.sep).filter(Boolean)) {
+    cur = path.join(cur, part);
+    let st;
+    try { st = fs.lstatSync(cur); } catch (_) { return false; }
+    if (st.isSymbolicLink()) return true;
+  }
+  return false;
+}
+
+function vlLegacyInventory(home) {
+  const stateRoot = path.join(home, '.local', 'state');
+  let names = [];
+  try { names = fs.readdirSync(stateRoot); } catch (_) { names = []; }
+  const entries = [];
+  for (const name of names.sort()) {
+    if (name !== 'vl' && !name.startsWith('vl-')) continue;
+    const dir = path.join(stateRoot, name);
+    let st;
+    try { st = fs.lstatSync(dir); } catch (_) { continue; }
+    if (!st.isDirectory() || st.isSymbolicLink()) continue;
+    const sessionsDir = path.join(dir, LEGACY_SESSIONS_REL);
+    // Nessun componente del percorso puo' essere un symlink: un symlink
+    // intermedio porterebbe l'inventario a elencare un albero esterno, che
+    // e' esattamente cio' che l'inventario legacy non deve fare.
+    if (hasSymlinkComponent(home, sessionsDir)) continue;
+    const sessions = [];
+    let hasSessionsDir = false;
+    try {
+      const sst = fs.lstatSync(sessionsDir);
+      if (sst.isDirectory() && !sst.isSymbolicLink()) {
+        hasSessionsDir = true;
+        for (const s of fs.readdirSync(sessionsDir).sort()) sessions.push(s);
+      }
+    } catch (_) { /* unreadable or absent: listed as found, sessions empty */ }
+    entries.push({
+      name,
+      sessionsDir: hasSessionsDir,
+      sessionCount: sessions.length,
+      ...(sessions.length > LEGACY_SESSIONS_CAP
+        ? { sessions: sessions.slice(0, LEGACY_SESSIONS_CAP), truncated: true }
+        : { sessions }),
+    });
+  }
+  return {
+    scanned: '.local/state',
+    entries,
+    moved: 0,
+    deleted: 0,
+    note: 'inventario read-only: nessuna migrazione, spostamento o cancellazione',
+  };
+}
+
+module.exports = {
+  requestVlNewSession,
+  consumeVlNewSession,
+  vlNewSessionStatus,
+  vlLegacyInventory,
+};

package/lib/mcp/tools.js

@@ -587,8 +587,8 @@ const TOOLS = [
       type: 'object',
       properties: {
         target: { type: 'string', description: 'id owner-qualified esatto restituito da nc_vl_nodes' },
-        kind: { type: 'string', enum: ['status', 'health', 'start', 'stop', 'restart', 'version', 'capabilities', 'logs', 'update_candidate', 'unpair'] },
-        args: { type: 'object', description: 'argomenti exact del comando bounded' },
+        kind: { type: 'string', description: 'Comando bounded. `prompt` porta testo dell utente (args.text, stringa <= 4 KiB) fino alla sessione del device; conferma solo via lastAck.', enum: ['status', 'health', 'start', 'stop', 'restart', 'version', 'capabilities', 'logs', 'update_candidate', 'unpair', 'prompt'] },
+        args: { type: 'object', description: 'argomenti exact del comando bounded; per `prompt` usare {text: string <= 4 KiB}' },
       },
       required: ['target', 'kind'],
     },
@@ -597,8 +597,24 @@ const TOOLS = [
       const target = parseVlTarget(argString(args, 'target', { required: true, max: 128 }));
       const kind = argString(args, 'kind', { required: true, max: 32 });
       const commandArgs = args.args === undefined ? {} : args.args;
-      if (!target || !commandArgs || typeof commandArgs !== 'object' || Array.isArray(commandArgs)
-        || JSON.stringify(commandArgs).length > 4096) throw new Error('target o args VL non validi');
+      if (!target || !commandArgs || typeof commandArgs !== 'object' || Array.isArray(commandArgs)) {
+        throw new Error('target o args VL non validi');
+      }
+      // `prompt` e' l'unico verbo che porta testo dell'utente fino alla sessione
+      // del device. Il tetto di 4 KiB vale sul testo (byte UTF-8), non sul JSON
+      // che lo impacchetta: un overflow va detto qui con un messaggio leggibile,
+      // non partire come `submitted` per farsi rifiutare dal device.
+      if (kind === 'prompt') {
+        const text = commandArgs.text;
+        if (typeof text !== 'string' || text.length < 1) {
+          throw new Error('nc_vl_command prompt: args.text deve essere una stringa non vuota');
+        }
+        if (Buffer.byteLength(text, 'utf8') > 4096) {
+          throw new Error('nc_vl_command prompt: args.text oltre 4 KiB (4096 byte UTF-8); accorciare il testo');
+        }
+      } else if (JSON.stringify(commandArgs).length > 4096) {
+        throw new Error('target o args VL non validi');
+      }
       const directory = await readVlDirectory(ctx);
       const node = directory.nodes.find((item) => item.id === target.id);
       if (!node) throw new Error(vlLookupFailure(directory, target));

package/lib/proxy/federation.js

@@ -428,7 +428,7 @@ function knownResource(resource) {
     || /^\/event-feed\/notices\/[0-9a-f-]{36}$/.test(resource)
     || resource === '/event-feed/notices/dismiss-all'
     || isPanelResource(resource)
-    || /^\/fleet\/(status|schema|definitions|credentials\/status|credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-model|edit-model|remove-model|model-test|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource);
+    || /^\/fleet\/(status|schema|definitions|credentials\/status|credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-model|edit-model|remove-model|model-test|define-cell|edit-cell|remove-cell|restore-cells|restore-engines|vl-new-session|vl-new-session-state|vl-legacy-inventory)$/.test(resource);
 }
 
 // Il pannello di una cella e' l'unica risorsa federata con un gate PER-PEER a
@@ -511,13 +511,16 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/diagnostics/logs') return method === 'GET' || method === 'DELETE';
   if (resource === '/diagnostics/verbose') return method === 'PATCH';
   if (resource === '/ws') return method === 'GET';
-  if (/^\/fleet\/(status|schema|definitions|credentials\/status)$/.test(resource)) return method === 'GET';
+  // La famiglia vl del fleet: le letture sono GET, le scritture POST. Lo
+  // stato della richiesta di sessione nuova sta con le altre: e' una GET
+  // read-only, e il suo bersaglio (la cella) e' dichiarato nello scope-guard.
+  if (/^\/fleet\/(status|schema|definitions|credentials\/status|vl-new-session-state|vl-legacy-inventory)$/.test(resource)) return method === 'GET';
   // `model-test` e' un POST che non muta niente: interroga il CATALOGO del
   // fornitore (`GET .../models`) con la credenziale di quel nodo e ne ricava un
   // enum. Non genera testo, quindi non consuma token. Resta comunque una
   // mutazione ai fini di READONLY (sotto): un nodo dichiarato di sola lettura
   // non emette richieste autenticate su comando di un peer.
-  if (/^\/fleet\/(credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-model|edit-model|remove-model|model-test|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource)) return method === 'POST';
+  if (/^\/fleet\/(credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-model|edit-model|remove-model|model-test|define-cell|edit-cell|remove-cell|restore-cells|restore-engines|vl-new-session)$/.test(resource)) return method === 'POST';
   // Notify: solo POST. `/events` e `/push/*` restano NON federati — SSE non
   // puo' autenticarsi col Bearer.
   //

package/lib/proxy/resource-acl.js

@@ -20,6 +20,15 @@ const CLASSES = Object.freeze({
   // authorized inventory is projected, and a peer with no visible cell sees none
   // of it.
   inventory: Object.freeze({ grants: [], needsVisibility: true }),
+  // The vl legacy inventory: a photo of the NODE state (the shared
+  // pre-contract directories), not a list of cells. Those directories have no
+  // reliable cell->session mapping, so the inventory cannot be projected onto
+  // a partial scope without inventing one: it is whole or nothing. The peer
+  // needs the operator grant AND a full scope. The authoritative check is the
+  // scope RESOLVED on the whole chain (lib/cells/scope-guard.js): this gate
+  // sees only the last hop, and a restricted origin must not inherit the
+  // promise of a wide deliverer.
+  'node-inventory': Object.freeze({ grants: ['peerOperatorAccess'], needsFullScope: true }),
   // Reading shared files: list and download, filtered by the owning cell.
   'files-read': Object.freeze({ grants: ['filesReadAccess'] }),
   // Choosing which cell of this node hosts the Live session.
@@ -94,10 +103,13 @@ function classifyResource(resource, method = 'GET') {
   // Fleet: the allowlist splits the family in two — the read alternatives are
   // GET, the rest are POST. A peer that is not an operator is refused by the
   // class gate; an operator no longer gets "resource-not-classified".
-  if (/^\/fleet\/(status|schema|definitions|credentials\/status)$/.test(resource)) {
+  if (/^\/fleet\/(status|schema|definitions|credentials\/status|vl-new-session-state)$/.test(resource)) {
     return m === 'GET' ? 'operator' : null;
   }
-  if (/^\/fleet\/(credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-model|edit-model|remove-model|model-test|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource)) {
+  // L'inventario legacy vl e' lo stato del NODO, non un elenco di celle: e'
+  // intero o niente (vedi la classe 'node-inventory' qui sopra).
+  if (resource === '/fleet/vl-legacy-inventory') return m === 'GET' ? 'node-inventory' : null;
+  if (/^\/fleet\/(credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-model|edit-model|remove-model|model-test|define-cell|edit-cell|remove-cell|restore-cells|restore-engines|vl-new-session)$/.test(resource)) {
     return m === 'POST' ? 'operator' : null;
   }
   if (resource === '/decks') return m === 'GET' || m === 'POST' ? 'operator' : null;
@@ -140,6 +152,9 @@ function allowedByClass(className, ingress) {
     if (ingress[grant] !== true) return false;
   }
   if (cls.needsVisibility === true && ingress.cellVisibility === 'none') return false;
+  // Una classe che si legge per intero non si presta a uno scope parziale:
+  // il peer deve vedere tutto quello che la risposta contiene.
+  if (cls.needsFullScope === true && ingress.cellVisibility !== 'all') return false;
   return true;
 }