@mmmbuto/nexuscrew 0.9.28 → 0.9.30

package/lib/fleet/managed.js

@@ -415,14 +415,14 @@ const OPENCODE_GO_PI_MODELS = Object.freeze(OPENCODE_GO_CHAT_MODELS.map((id) =>
 
 const CUSTOM_KEYS = ['displayName', 'protocol', 'baseUrl', 'envKey', 'providerId'];
 const MANAGED_KEYS = new Set(['client', 'provider', 'credentialProfile', 'model', 'permissionPolicy', 'credentialSourcePolicy', 'envPassthrough', ...CUSTOM_KEYS]);
-// D3: massimo numero di nomi in `envPassthrough`. L'allowlist e' opt-in e per
+// Massimo numero di nomi in `envPassthrough`. L'allowlist e' opt-in e per
 // nome, mai un passthrough in blocco: un tetto basso ferma una lista incontrollata.
 const MAX_ENV_PASSTHROUGH = 32;
 const CODEX_APP_SERVER_IDENTITY_REQUIRED = 'CODEX_APP_SERVER_IDENTITY_REQUIRED';
 const CODEX_APP_SERVER_IDENTITY_REQUIRED_DEFAULT = '1';
 // Explicit credential source policy. Default 'auto' preserves the legacy
 // resolution order (runtime -> store -> shell -> key files -> legacy) so a
-// pre-WP1 fleet.json migrates no-op: no existing cell changes resolution.
+// Pre- fleet.json migrates no-op: no existing cell changes resolution.
 const CREDENTIAL_SOURCES = Object.freeze(['environment', 'nexuscrew-store', 'auto']);
 // I valori che `credential().source` puo' assumere, e che escono verso la UI in
 // `describeManaged().credentialSource` / `describeCatalogCredential()`. La UI li
@@ -517,7 +517,7 @@ const CATALOG = Object.freeze([
   // VL/Vivling (repository `vl`): runtime TUI locale. Auth propria del runtime
   // in OGNI variante (config.toml / VL_API_KEY): NexusCrew non legge ne' copia
   // credenziali (auth 'none') — la chiave, dove serve, sale per NOME via
-  // envPassthrough (D3), mai come valore, mai su argv. vl.native e' «usa la tua
+  // EnvPassthrough, mai come valore, mai su argv. vl.native e' «usa la tua
   // configurazione»: NESSUNA env provider/base_url, perche' i default interni del
   // runtime sono gia' openai-compat + localhost:11434 e le VL_* ambientali
   // sovrascrivono il config.toml (comporle qui cancellerebbe default_profile in
@@ -615,7 +615,7 @@ function profileFor(client, provider, credentialProfile) {
     && (p.credentialProfile || '') === (credentialProfile || '')) || null;
 }
 
-// D3: validazione unica dell'allowlist envPassthrough (nomi, mai valori): la
+// Validazione unica dell'allowlist envPassthrough (nomi, mai valori): la
 // usano sia la dichiarazione dell'operatore sia il default portato dal profilo
 // del catalogo, cosi' i due percorsi non possono divergere sui vincoli.
 function sanitizeEnvPassthrough(list) {
@@ -700,7 +700,7 @@ function normalizeManagedSpec(value, { extraModels = null, engineId = null, onIs
     if (!displayName || displayName.length > 64 || /[\x00-\x1f\x7f]/.test(displayName)) return null;
     if (!validBaseUrl(baseUrl)) return null;
     // vl: la chiave NON viaggia come envKey copiata dallo store (pattern degli
-    // altri client) ma per NOME via envPassthrough (D3) — un custom vl verso un
+    // Altri client) ma per NOME via envPassthrough — un custom vl verso un
     // endpoint senza auth (Ollama remoto) non dichiara nessuna chiave, quindi
     // envKey vuota e' legittima solo per vl. Se dichiarata, resta un nome valido.
     if (profile.client === 'vl' ? (envKey !== '' && !ENV_KEY_RE.test(envKey)) : !ENV_KEY_RE.test(envKey)) return issue('envKey', envKey, `consentito ${ENV_KEY_RE} (obbligatorio; vuoto ammesso solo per il client vl)`);
@@ -708,7 +708,7 @@ function normalizeManagedSpec(value, { extraModels = null, engineId = null, onIs
     if (!model || !(profile.protocols || [profile.protocol]).includes(protocol)) return issue('protocol', protocol, `protocollo non supportato dal profilo (ammessi: ${(profile.protocols || [profile.protocol]).join(', ')})`);
     Object.assign(out, { displayName, baseUrl, ...(envKey ? { envKey } : {}), protocol, providerId });
   }
-  // D3: envPassthrough e' un'allowlist di NOMI di variabili d'ambiente che il
+  // EnvPassthrough e' un'allowlist di NOMI di variabili d'ambiente che il
   // child deve ricevere, risolti a runtime dalle credentialSources (dopo i rami
   // provider in resolveManagedEngine). E' opt-in e per nome: MAI un passthrough
   // in blocco dell'ambiente, solo i nomi elencati — ciascuno un nome env valido.
@@ -1227,9 +1227,9 @@ function describeManaged(spec, cfg = {}) {
   const delegatedPiAuth = profile.client === 'pi' && profile.provider !== 'custom'
     && profile.delegatePiAuth !== false;
   // vl: l'autenticazione e' del runtime in OGNI variante (auth 'none', o chiave
-  // che sale per NOME via envPassthrough/D3 quando il profilo la dichiara). Il
+  // Che sale per NOME via envPassthrough/ quando il profilo la dichiara). Il
   // verdetto configured non puo' dipendere da una credenziale che NexusCrew non
-  // possiede: il fail-closed giusto e' quello del D3, che NOMINA il nome mancante.
+  // Possiede: il fail-closed giusto e' quello del, che NOMINA il nome mancante.
   const authConfigured = delegatedPiAuth || profile.auth === 'login' || profile.auth === 'none'
     || profile.client === 'vl' || !!cred.value;
   let configured = !!binary && authConfigured;
@@ -1564,11 +1564,11 @@ function writePiProviderExtension(spec, home, declaredModels) {
   return target;
 }
 
-// V-69 — prompt per-cella per il runtime vl. Dalla 0.3.1 vl legge
-// VL_SYSTEM_APPEND_FILE e COMPONE il file sul proprio system (VL_SYSTEM resta
-// «sostituisci» e non si tocca: un wrapper vivo dipende da quel significato).
-// Il file porta il prompt della cella e le istruzioni companion MCP: vl non ha
-// client MCP, quello e' l'unico punto in cui il testo lo raggiunge. Stessa
+// Per-cell prompt for the vl runtime: since 0.3.1 vl reads
+// VL_SYSTEM_APPEND_FILE and composes the file on its own system (VL_SYSTEM
+// keeps its "replace" meaning and is untouched: a live wrapper depends on it).
+// The file carries the cell prompt and the MCP companion instructions: vl has
+// no MCP client, that is the only point where the text reaches it.
 // forma e stesso posto di writePiProviderExtension: generato sotto
 // ~/.nexuscrew, atomico (tmp+rename), mai credenziali — il contenuto e'
 // cell.prompt piu' testo statico, nessun valore letto dalle sorgenti
@@ -1775,9 +1775,9 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
   // divergere. Divergono, e una cella standalone muore sull'handshake.
   let identityChannel = null;
   let identityAuthorityUnavailable = '';
-  // V-69: motivo per cui il prompt per-cella di vl NON e' stato composto
-  // (versione del runtime che non regge, o file non scrivibile in sicurezza).
-  // Stringa vuota = consegnato. Sale con l'engine risolto come vlPromptDegraded.
+  // Why the vl per-cell prompt was NOT composed (runtime version that cannot
+  // hold it, or a file that cannot be written safely).
+  // Empty string = delivered. Surfaces with the engine resolved as vlPromptDegraded.
   let vlPromptDegraded = '';
   // I due profili Claude con configurazione privata: perdono gli MCP del file
   // principale e vanno ricollegati (vedi `sharedMcpArgs`).
@@ -2042,12 +2042,12 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     // TUI interattivo nella cwd della cella.
     if (model) args.push('--model', model);
   } else if (spec.client === 'vl') {
-    // VL/Vivling runtime TUI: auth gestita dal runtime in ogni variante
-    // (config.toml / VL_API_KEY per nome via envPassthrough, D3), mai
-    // credenziali su argv. Il modello scelto nella UI viaggia via VL_MODEL
-    // (V-69), il prompt di cella via file sul system del runtime
-    // (VL_SYSTEM_APPEND_FILE, gate qui sotto); `vl --profile` esiste ma resta
-    // dell'operatore. Nessun --model su argv: la TUI parte senza argomenti.
+    // VL/Vivling runtime TUI: auth is handled by the runtime in every variant
+    // (config.toml / VL_API_KEY by name via envPassthrough), never
+    // credentials on argv. The model chosen in the UI travels via VL_MODEL
+    // and the per-cell prompt via a file on the runtime system
+    // (VL_SYSTEM_APPEND_FILE, gate below); `vl --profile` remains
+    // the operator's choice. No --model on argv: the TUI starts without arguments.
     if (model) env.VL_MODEL = model;
     // vl.native e' «usa la tua configurazione»: NESSUNA env provider/base_url.
     // I default interni del runtime sono gia' openai-compat + localhost:11434,
@@ -2079,12 +2079,12 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
       env.VL_PROVIDER = profile.vlProvider;
       env.VL_BASE_URL = profile.endpoint;
     }
-    // V-69 — prompt per-cella: file composto sul system del runtime
-    // (VL_SYSTEM_APPEND_FILE). Il gate di versione sta nel codice, non nella
-    // speranza: sotto la 0.3.1 la variabile e' ignorata in silenzio, e una
-    // cella che parte senza il proprio prompt senza dirlo e' il difetto che
-    // questo ramo chiude, non il rimedio. Degradare = NON comporre la env
-    // (mai una promessa che il runtime scarta) + dichiarare il motivo.
+    // Per-cell prompt: file composed on the runtime system
+    // (VL_SYSTEM_APPEND_FILE). The version gate lives in code, not in hope:
+    // below 0.3.1 the variable is silently ignored, and a cell starting without
+    // its own prompt without saying so is the defect this branch closes,
+    // not the remedy. Degrading = NOT composing the env (never a promise the
+    // runtime discards) + declaring the reason.
     const gate = vlSystemAppendGate(info.binary, cfg);
     if (gate.ok) {
       try {
@@ -2190,17 +2190,17 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
   // (finding separato, fuori da questa patch).
   const promptViaDelivery = spec.client === 'kimi'
     || (spec.client === 'claude' && spec.provider === 'kimi-code');
-  // vl e' una TUI senza superficie prompt (`vl [OPTIONS]`, nessun flag prompt):
-  // non riceve MAI il prompt di cella su argv — dalla V-69 viaggia nel file
-  // per-cella composto dal ramo vl (VL_SYSTEM_APPEND_FILE). send-keys non si
-  // applica: il classifier di deliverBootstrapPrompt copre solo kimi/claude, e
-  // vl parte subito senza attese.
+  // vl is a TUI without a prompt surface (`vl [OPTIONS]`, no prompt flag):
+  // it NEVER receives the per-cell prompt on argv — it travels in the
+  // per-cell file composed by the vl branch (VL_SYSTEM_APPEND_FILE).
+  // send-keys does not apply: the deliverBootstrapPrompt classifier covers
+  // only kimi/claude, and vl starts immediately without waits.
   if (spec.client !== 'shell' && spec.client !== 'vl' && !promptViaDelivery && cell?.prompt) args.push(cell.prompt);
   // nexuscrew-store source: neutralize the profile's env set in the composed
   // child env (unset, never empty), so the runtime cannot leak credentials that
   // the local store is meant to own.
   applyStoreNeutralization(env, spec, profile);
-  // D3: resolve envPassthrough AFTER the provider branches. Each declared name is
+  // Resolve envPassthrough AFTER the provider branches. Each declared name is
   // read from the credentialSources (same order as credential() 'auto': runtime
   // -> store -> shell -> key files -> legacy) and injected into the child env.
   // Per nome, mai in blocco. A name that is declared but absent from every source
@@ -2244,7 +2244,7 @@ function publicCatalog() {
     auth: p.auth, endpoint: p.endpoint || '', model: p.model || '', models: [...(p.models || [])],
     protocols: [...(p.protocols || [p.protocol])], supportsUnsafe: !['pi', 'shell', 'vl'].includes(p.client), requiresModel: !!p.requiresModel || !!p.custom,
     permissionPolicyDefault: p.client === 'claude' ? 'unsafe' : 'standard',
-    // DEC2: solo il client claude riceve MCP gestito da NexusCrew (cellMcpArgs/
+    // Solo il client claude riceve MCP gestito da NexusCrew (cellMcpArgs
     // sharedMcpArgs nel ramo claude di resolveManagedEngine). Per ogni altro
     // client (codex, vl, kimi, pi, agy, grok) `cell.mcp` e' INERTE: la cella lo
     // accetta ma non ha effetto, perche' i server MCP li registra il client nel

package/lib/fleet/prompt-delivery.js

@@ -28,7 +28,7 @@ const PANE_STATES = Object.freeze([
   'ready', 'busy', 'not-ready-auth', 'not-ready-consent', 'not-ready-onboarding', 'unknown',
 ]);
 
-// Esiti bounded della consegna (prompt.reason in API: closed enum, G5).
+// Esiti bounded della consegna (prompt.reason in API: closed enum).
 const DELIVERY_STATES = Object.freeze([
   'submitted',             // paste ok + pane riverificato + Enter ok
   'staged-not-submitted',  // paste ok, Enter fallito: testo forse nel composer
@@ -36,16 +36,16 @@ const DELIVERY_STATES = Object.freeze([
   'failed-pre-paste',      // resolve/load certamente falliti (anche dopo 1 retry)
   'skipped-not-ready',     // classifier not-ready a fine attesa bounded (kind in notReady)
   'skipped-unknown',       // classifier mai ready entro il timeout
-  'prompt-rejected',       // byte di controllo nel prompt (policy §9e)
-  'cancelled',             // generazione terminata durante l'attesa/consegna (R3)
+  'prompt-rejected',       // control bytes found in the prompt (policy check)
+  'cancelled',             // Generazione terminata durante l'attesa/consegna
   'report-timeout',        // up() non ha ricevuto l'esito del launcher entro il bound
 ]);
 
-// Codici bounded actionRequired (G5). Nessuna inferenza "rifiutato": il marker
+// Codici bounded actionRequired. Nessuna inferenza "rifiutato": il marker
 // TUI prova solo che serve un'azione nel terminale della cella.
 const ACTION_CODES = Object.freeze(['KIMI_AUTH_ACTION_REQUIRED', 'CLIENT_INTERACTION_REQUIRED']);
 
-// Slug recovery bounded (R10): l'API trasporta SOLO {code, recovery}; il testo
+// Slug recovery bounded: l'API trasporta SOLO {code, recovery}; il testo
 // e' mappato localmente dalla PWA via i18n (fleet-recovery-<slug>), mai inviato
 // dal server (un nodo remoto federato non deve poter iniettare testo libero).
 const RECOVERY_SLUGS = Object.freeze([
@@ -65,7 +65,7 @@ const MODAL_NOT_READY = Object.freeze([
 
 // Marker ancorati alla CODA visibile (status bar / righe finali): lo stesso
 // testo in scrollback, nel corpo conversazione o in forma diversa non deve
-// classificare (R7: il marker auth e' la stringa ESATTA di status bar, non un
+// Classificare (il marker auth e' la stringa ESATTA di status bar, non un
 // "Not logged in" qualunque). Live-verificati: claude 2.1.220 (status bar
 // "Not logged in · Run /login"), kimi 0.31.1 (welcome "Run /login or
 // /provider", "Model: not set").
@@ -99,7 +99,7 @@ function classifyPane(captured, client) {
   for (const [state, re] of TAIL_NOT_READY) if (re.test(tail)) return state;
   if (BUSY_TAIL.test(tail)) return 'busy';
   if (client === 'kimi') {
-    // READY positivo Kimi: box di input corrente E modello configurato (G2).
+    // READY positivo Kimi: box di input corrente E modello configurato.
     // Il solo "Model:" non basta; la sola box non basta (presente anche da
     // logged-out). Il welcome logged-out e' gia' intercettato dai marker
     // not-ready qui sopra; se scrolla via senza login resta 'unknown' (safe).
@@ -132,7 +132,7 @@ function classifyPane(captured, client) {
 }
 
 // vlPaneReadiness(tmuxBin, target, opts) -> { ready, degraded }
-// DEC1: content-readiness di una cella vl via pane — il marcatore [o] + coda
+// Content-readiness di una cella vl via pane — il marcatore [o] + coda
 // `esc quit · ^y yield` riconosciuto da classifyPane(text,'vl'). E' il PUNTO DI
 // INNESTO della readiness vl: quando arrivera' l'adapter di runtime, la
 // readiness si misurera' sul socket di controllo (vl-core/src/transport.rs) e
@@ -174,7 +174,7 @@ function clampInt(value, dflt, min, max) {
 //           paneTarget (%N opzionale), readyWaitMs, pollMs, settleMs, tmpdir,
 //           tmuxExecImpl, captureImpl, sleepImpl, nowImpl, fsImpl, isCancelled }
 // reason e' SEMPRE lo state (closed enum); notReady e' il kind bounded o ''.
-// isCancelled() (R3): valutato ad OGNI poll, prima del paste e prima dell'
+// IsCancelled: valutato ad OGNI poll, prima del paste e prima dell'
 // Enter; se true la consegna si ferma subito ('cancelled') senza paste/Enter —
 // cell-exec cancella la delivery quando la generazione termina, cosi' un
 // polling in volo non puo' mai iniettare nella generazione successiva.
@@ -219,7 +219,7 @@ async function deliverBootstrapPrompt(opts = {}) {
 
   // (2) Consegna AT-MOST-ONCE: un solo paste per generazione. Il retry copre
   // SOLO fallimenti certi pre-paste (resolve/load); dopo qualsiasi tentativo
-  // di paste-buffer non esiste retry automatico (G1).
+  // Di paste-buffer non esiste retry automatico.
   let attempts = 0;
   for (;;) {
     if (cancelled()) return done(false, 'cancelled', '', attempts);
@@ -240,7 +240,7 @@ async function deliverBootstrapPrompt(opts = {}) {
       if (cancelled()) return done(false, 'delivery-unknown', '', attempts);
       const enter = await exec(tmuxBin, ['send-keys', '-t', stage.paneId, 'Enter'], { env });
       if (enter.err) return done(false, 'staged-not-submitted', '', attempts);
-      // R9: cancel con Enter appena partito -> la generazione e' morta con un
+      // Cancel con Enter appena partito -> la generazione e' morta con un
       // submit in volo: esito incerto (residuo PTY possibile), mai 'submitted'.
       if (cancelled()) return done(false, 'delivery-unknown', '', attempts);
       return done(true, 'submitted', '', attempts);
@@ -259,7 +259,7 @@ async function deliverBootstrapPrompt(opts = {}) {
   }
 }
 
-// waitDeliveryReport(tmuxBin, target, opts) -> delivery-like | null (R2).
+// WaitDeliveryReport(tmuxBin, target, opts) -> delivery-like null.
 // Il launcher supervisionato (cell-exec) e' l'UNICO owner della consegna per
 // TUTTE le generazioni degli engine Kimi e pubblica l'esito bounded sull'
 // opzione tmux di pane @nc_delivery ('<state>' o '<state>:<notReady>', solo
@@ -294,7 +294,7 @@ async function waitDeliveryReport(tmuxBin, target, { env, exec, sleepImpl, nowIm
 // actionRequiredFor(client, provider, delivery) -> null | { code, recovery }
 // Mappa bounded delivery -> azione operatore. Solo skip per not-ready/unknown
 // producono actionRequired; i fallimenti di trasporto restano nel prompt.state.
-// R10: SOLO {code, recovery} closed enum/slug — il testo e' i18n locale PWA.
+// SOLO {code, recovery} closed enum/slug — il testo e' i18n locale PWA.
 function actionRequiredFor(client, provider, delivery) {
   if (!delivery || delivery.delivered) return null;
   if (delivery.state !== 'skipped-not-ready' && delivery.state !== 'skipped-unknown') return null;

package/lib/fleet/routes.js

@@ -10,9 +10,9 @@ function capList(fleet) {
   return typeof fleet.capabilities === 'function' ? fleet.capabilities() : DEFAULT_CAPS;
 }
 
-// Design §9c: una route per un metodo non supportato dal provider ritorna 501
-// (mai 404/502 ambigui). Gli errori nativi del builtin (400/403/409) passano
-// invece nel guard con il loro status.
+// A route for a method unsupported by the provider returns 501
+// (never ambiguous 404/502). The builtin native errors (400/403/409) pass
+// through the guard with their own status.
 function requireCap(fleet, cap) {
   if (!capList(fleet).includes(cap)) {
     const e = new Error('not supported by this fleet provider');
@@ -53,6 +53,11 @@ function fleetRoutes(fleetP, cfg = {}) {
       if (opts.action) emit('info', 'FLEET_ACTION_COMPLETED', 'Fleet action completed', {
         action: opts.action, cell: safeCell(body), state: opts.action === 'down' ? 'stopped' : 'ready',
       });
+      if (opts.action && typeof cfg.onFleetStateChange === 'function') {
+        try {
+          cfg.onFleetStateChange({ cell: safeCell(body), active: opts.action !== 'down', action: opts.action });
+        } catch (_) { /* observability never breaks the action */ }
+      }
       res.json(result);
     } catch (e) {
       if (opts.action) {
@@ -63,7 +68,7 @@ function fleetRoutes(fleetP, cfg = {}) {
         else emit('warn', 'FLEET_ACTION_FAILED', 'Fleet action failed', {
           action: opts.action, cell: safeCell(req.body), state: 'failed',
           status: e.status || 500,
-          // Cause-preserving (T4): bounded enum only (lib/fleet/causes.js). The
+          // Cause-preserving: bounded enum only (lib/fleet/causes.js). The
           // cause triple is {status, code, phase}; no free message, cwd/path,
           // argv, env, prompt, token or credential ever enters here. Untagged /
           // legacy errors degrade to the bounded UNKNOWN fallback.
@@ -81,8 +86,8 @@ function fleetRoutes(fleetP, cfg = {}) {
     }
   };
 
-  // /status espone anche `provider` e `capabilities` (design §9b/§9c), oltre ai
-  // campi storici (available/cells/engines).
+  // /status also exposes `provider` and `capabilities`, besides the
+  // historical fields (available/cells/engines).
   r.get('/status', async (_req, res) => {
     try {
       const fleet = await fleetP;
@@ -90,10 +95,10 @@ function fleetRoutes(fleetP, cfg = {}) {
         return res.json({
           available: false,
           provider: fleet.provider || 'disabled',
-          bootOwner: 'none', // §9b: provider non disponibile -> nessun boot owner
+          bootOwner: 'none', // provider unavailable -> no boot owner
           capabilities: capList(fleet),
           ...(fleet.reason ? { reason: fleet.reason } : {}),
-          // R33: il codice macchina del boot bloccato viaggia fino al client.
+          // Il codice macchina del boot bloccato viaggia fino al client.
           // La policy di lettura decide su QUESTO, non sulla prosa del reason
           // (la prosa resta ripiego per i reason che un codice non ce l'hanno).
           // Senza campo dal provider, la risposta semplicemente non lo ha.
@@ -143,8 +148,8 @@ function fleetRoutes(fleetP, cfg = {}) {
     return f.boot(String(b.cell || ''), b.enabled === true);
   }, { mutate: true }));
 
-  // --- Estensione B4.2: schema + define/edit/remove (engine e cell) ---
-  // Ogni route negozia la capability del provider: mancante → 501 (§9c).
+  // --- Extension: schema + define/edit/remove (engine and cell) ---
+  // Every route negotiates the provider capability: missing -> 501.
   r.get('/schema', guard((f) => { requireCap(f, 'schema'); return f.schema(); }));
   r.get('/definitions', guard((f) => { requireCap(f, 'definitions'); return f.definitions(); }));
   r.get('/credentials/status', guard((f) => {

package/lib/fleet/runtime.js

@@ -200,7 +200,7 @@ function createBuiltinRuntime(ctx) {
     return cache.defs.cells.some((c) => c.tmuxSession === String(name));
   }
 
-  // up — ordine obbligatorio (design §9a, task B4.2).
+  // up — mandatory order.
   // 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.
@@ -220,12 +220,12 @@ function createBuiltinRuntime(ctx) {
         throw httpError(400, `engine managed non configurato (${engine.id}): ${resolved.reason}`, null, { phase: 'preflight', code });
       }
       launchEngine = resolved.engine;
-      // V-69: una cella vl il cui runtime non regge il prompt per-cella
-      // (VL_SYSTEM_APPEND_FILE, 0.3.1+) DEGRADA dichiarando — stessa forma di
-      // readinessDegraded (DEC1): la cella parte senza la propria identita' e
-      // l'operatore lo vede (log qui + flag nel risultato, consumato dalla UI).
-      // Mai in silenzio: la partenza silenziosa senza prompt e' il difetto che
-      // V-69 chiude.
+      // A vl cell whose runtime cannot hold the per-cell prompt
+      // (VL_SYSTEM_APPEND_FILE, 0.3.1+) DEGRADES by declaring it — same
+      // shape as readinessDegraded: the cell starts without its own identity
+      // and the operator sees it (log here + flag in the result, consumed by the UI).
+      // Never in silence: a silent start without the prompt is the defect
+      // this closes.
       if (launchEngine.vlPromptDegraded) {
         const log = typeof cfg.log === 'function' ? cfg.log : console.warn;
         log(`fleet vl ${cell.id}: ${launchEngine.vlPromptDegraded}`);
@@ -311,7 +311,7 @@ function createBuiltinRuntime(ctx) {
             readyMs: Math.max(0, Math.min(30000, Number(cfg.sendKeysReadyMs) || readyMs)),
             // Solo gli engine managed Kimi (kimi.native / claude.kimi-code) hanno
             // la delivery classificata at-most-once ai restart; gli engine custom
-            // send-keys conservano il reinject legacy senza Enter (0.8.47 G4).
+            // Send-keys conservano il reinject legacy senza Enter (0.8.47).
             client: engine.managed && engine.managed.client === 'kimi' ? 'kimi'
               : (engine.managed && engine.managed.provider === 'kimi-code' ? 'claude' : ''),
             readyWaitMs: Math.max(0, Math.min(120000, Number(cfg.bootstrapReadyWaitMs) || 15000)),
@@ -337,11 +337,11 @@ function createBuiltinRuntime(ctx) {
     };
     const tmuxChild = composeClientInvocation(tmuxLaunchEngine, cell);
 
-    // Avvio staged (design §3.3): crea il pane con un placeholder inerte trusted
-    // (cell-hold.js), arma remain-on-exit window-local sul @N, poi respawn-pane -k
-    // verso cell-exec sul %N esatto. Cosi' remain-on-exit e' gia' ON quando il vero
-    // child puo' terminare: nessuna finestra scomparsa, nessun NEW_SESSION_FAILED
-    // che maschera l'exit reale. Il nome sessione e' gia' validato tmux-safe (v2
+    // Staged start: creates the pane with a trusted inert placeholder
+    // (cell-hold.js), arms window-local remain-on-exit on the @N, then
+    // respawn-pane -k to cell-exec on the exact %N. So remain-on-exit is already
+    // ON when the real child can terminate: no vanished window, no
+    // NEW_SESSION_FAILED masking the real exit.
     // per id puntati, definitions.js); gli step critici usano gli ID restituiti
     // da tmux ($N/@N/%N). respawn-pane -k preserva il pane ID: il %N catturato
     // qui resta valido per readiness e prompt. Nessuna shell string, nessun
@@ -357,7 +357,7 @@ function createBuiltinRuntime(ctx) {
       // new-session fallita: nessuna sessione creata. Revoca il ticket (il child
       // non partira' mai) prima di propagare l'errore.
       try { await launchBroker.revoke?.(ticket.nonce); } catch (_) { /* best-effort */ }
-      // Redazione (§9h): lo stderr di tmux puo' ecoare argv/env del comando lanciato.
+      // Redaction: the tmux stderr can echo argv/env of the launched command.
       const dup = /duplicate session/i.test(create.stderr);
       const why = dup
         ? 'sessione già in esecuzione'
@@ -434,8 +434,8 @@ function createBuiltinRuntime(ctx) {
       ['respawn-pane', '-k', '-c', realCwd, '-t', paneId, tmuxChild.command, ...tmuxChild.args],
       { env: minimalEnv() });
     if (respawn.err) {
-      // respawn fallito dopo issue(): il nonce va revocato/consumato prima
-      // dell'errore (design §3.3), poi cleanup della sessione-pannello.
+      // respawn failed after issue(): the nonce must be revoked/consumed first
+      // before surfacing the error, then cleanup of the panel session.
       await cleanupLaunch();
       throw httpError(500,
         `tmux respawn-pane failed: ${redactSecrets(respawn.stderr.trim() || respawn.err.message, launchEngine, cell)}`,
@@ -478,7 +478,7 @@ function createBuiltinRuntime(ctx) {
           `comando Shell terminato subito${status}: ${diagnostic || 'verifica command, PATH e configurazione della shell'}`,
           null, { phase: 'readiness', code: 'SHELL_COMMAND_FAILED' });
       }
-      // Cause-preserving (T4): distinguish a cell-client spawn failure (the
+      // Cause-preserving: distinguish a cell-client spawn failure (the
       // captured pane carries the stable 'cell spawn failed:' marker produced by
       // cell-exec.js) from a generic early exit. Both stay on the readiness
       // surface; the spawn branch keeps CELL_SPAWN_FAILED sanitized downstream.
@@ -491,7 +491,7 @@ function createBuiltinRuntime(ctx) {
         ['set-option', '-w', '-t', readiness.target, 'remain-on-exit', 'off'], { env: minimalEnv(), timeoutMs: 2000 });
     }
 
-    // DEC1: content-readiness vl (marcatore [o] nel pane). MAI fail-closed: se
+    // Content-readiness vl (marcatore [o] nel pane). MAI fail-closed: se
     // entro il timeout il marcatore non compare DEGRADA e procede come se pronta
     // (una cella che parte oggi deve partire anche domani), lasciando traccia
     // nel risultato. vlPaneReadiness e' il punto di innesto sostituibile quando
@@ -514,14 +514,14 @@ function createBuiltinRuntime(ctx) {
       };
     }
 
-    // (6) prompt: due percorsi distinti (0.8.47, R2 single-owner).
+    // (6) prompt: two distinct paths (0.8.47, single-owner).
     //  - managed kimi.native / claude.kimi-code: la consegna e' posseduta SOLO
     //    dal supervisore (cell-exec) per TUTTE le generazioni; qui si legge
     //    l'esito bounded (@nc_delivery sul pane) con attesa bounded. Mai paste/
     //    Enter dal runtime: niente doppia delivery se gen0 muore durante
     //    l'attesa e gen1 parte sotto il supervisore.
     //  - engine custom promptMode 'send-keys': injectPrompt legacy (bracketed
-    //    paste SENZA Enter, contratto invariato — G4), target %N esatto.
+    // Paste SENZA Enter, contratto invariato —), target %N esatto.
     let prompt = null;
     let actionRequired = null;
     if (launchEngine.promptMode === 'send-keys' && cell.prompt) {
@@ -551,7 +551,7 @@ function createBuiltinRuntime(ctx) {
           env: minimalEnv(),
           readyMs: cfg.sendKeysReadyMs != null ? cfg.sendKeysReadyMs : readyMs,
           target,
-          engine: launchEngine, cell, // per la redazione del reason se paste-buffer fallisce (§9h)
+          engine: launchEngine, cell, // to redact the reason if the paste-buffer fails
         });
       }
     }
@@ -560,9 +560,9 @@ function createBuiltinRuntime(ctx) {
       ok: true, cell: cellId, session: cell.tmuxSession, prompt,
       ...(actionRequired ? { actionRequired } : {}),
       ...(readinessDegraded ? { readinessDegraded: true } : {}),
-      // V-69: prompt di cella non consegnato a una cella vl (runtime vecchio o
-      // file non scrivibile). Booleano strict come readinessDegraded: il
-      // payload puo' arrivare da un nodo federato e il testo e' i18n locale.
+      // Per-cell prompt not delivered to a vl cell (old runtime or
+      // unwritable file). Strict boolean like readinessDegraded: the
+      // payload may come from a federated node and the text is local i18n.
       ...(launchEngine.vlPromptDegraded ? { vlPromptDegraded: true } : {}),
     };
   }