@mmmbuto/nexuscrew 0.9.29 → 0.9.30

package/lib/fleet/builtin.js

@@ -2,7 +2,7 @@
 // Fleet built-in. FACADE: espone available/status/up/down/engine/boot e
 // isCellSession leggendo le definizioni da ~/.nexuscrew/fleet.json tramite
 // lib/fleet/definitions.js, insieme a define*/edit*/remove* +
-// schema + capabilities (design §4b/§9c).
+// schema + capabilities.
 //
 // La responsabilita' runtime/launch (status/up/down/restart + launch/readiness
 // helpers) e' stata estratta in modo behavior-preserving in:
@@ -16,16 +16,16 @@
 // Agnostico: non conosce "claude"/"glm"/"codex" — lancia solo command+args
 // dichiarati.
 //
-// Sicurezza (design §6 / §9a / §9d / §9e) — invariata, vedi launch.js/runtime.js:
+// Security model — unchanged, see 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.
 //  - 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 bracketed paste; se il command e' gia'
-//    uscito (sessione morta) NON digita (§9e).
+//  - READONLY (cfg.readonlyDefault===true | NEXUSCREW_READONLY=1) blocks every
+//    fleet mutation and every up: only status/schema/capabilities pass.
+//  - promptMode 'send-keys' injects via bracketed paste; when the command already
+//    exited (dead session) it does not type.
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
@@ -125,7 +125,7 @@ function backfillShellEngine(defsPath, defs, log) {
   return esito || defs;
 }
 
-// Backfill platform-aware dell'engine Agy primario (design §4.2): installazioni
+// Platform-aware backfill of the primary agy engine (idempotent, non-destructive).
 // esistenti su Linux/macOS non-Termux ricevono agy.native in modo idempotente e
 // non distruttivo. Su altre piattaforme (Termux/Windows) e' un no-op: agy non e'
 // un client primario supportato li' e l'utente puo comunque usarlo via shell.local
@@ -453,7 +453,7 @@ function applyCellTransition(target, engineId, { model, hasModel, policy, hasPol
 }
 
 // ---------------------------------------------------------------------------
-// cwd portabile (design §4.3). resolveCellCwd riconcilia cwd (assoluta) e
+// Portable cwd: resolveCellCwd reconciles the absolute cwd and cwdRel before every write.
 // cwdRel (home-relative) in una COPPIA COERENTE prima di ogni scrittura:
 //   - solo cwd (assoluta valida) -> deriva cwdRel
 //   - solo cwdRel (valida)        -> calcola la cwd assoluta target
@@ -582,7 +582,7 @@ async function createBuiltinFleet(cfg = {}) {
   const off = {
     available: false, provider: 'builtin',
     isCellSession: () => false, capabilities: () => [],
-    // B4: close() sempre sicura su qualunque Fleet restituita, anche unavailable:
+    // Close sempre sicura su qualunque Fleet restituita, anche unavailable:
     // il caller non deve distinguere `off` dalla Fleet reale.
     close: async () => {},
   };
@@ -609,7 +609,7 @@ async function createBuiltinFleet(cfg = {}) {
   // early return segue la creazione del manager, e la creazione avviene dopo tutti i
   // gate noti. Manternerla richiede che ogni nuovo gate resti qui sopra.
 
-  // Bootstrap: fleet.json valido? garbage -> unavailable (fail-closed, design §7).
+  // Bootstrap: a valid fleet.json? Garbage -> unavailable (fail-closed).
   // ENOENT (missing) o parse invalido -> off (unavailable legittimo, fail-closed);
   // EACCES/ELOOP sul lstat (file presente ma non verificabile) -> off CON reason,
   // perche' "non ho potuto guardare" e' un problema diverso da "non c'e'" o "e'
@@ -733,8 +733,8 @@ async function createBuiltinFleet(cfg = {}) {
     identityAuthority,
     identityDaemonCredential: cfg.identityDaemonCredential,
     identityLauncherCredential: cfg.identityLauncherCredential,
-    // R3.1.1: la connessione broker one-shot resta APERTA dopo il payload e diviene
-    // il canale lease del supervisore.
+    // The one-shot broker connection stays OPEN after the payload and becomes
+    // the supervisor lease channel.
     ...(leaseManager ? {
       onLease: (socket, lease) => {
         // da revisione interna: attachInitial restituisce false se la
@@ -1363,7 +1363,7 @@ async function createBuiltinFleet(cfg = {}) {
     return credentialStatus();
   }
 
-  // schema() — descrittore campi per editor UI schema-driven (design §5/§9f).
+  // schema() — field descriptor for the schema-driven UI editor.
   function schema() {
     return {
       schemaVersion: 1,
@@ -1482,8 +1482,8 @@ async function createBuiltinFleet(cfg = {}) {
     schema, definitions, capabilities,
     credentialStatus, setLocalCredential, removeLocalCredential, testModel,
     defineModel, removeModel, close,
-    // Fetta 2b (D3): il lease Live esposto alle route /api/lease, che il bridge
-    // MCP delle celle consuma per register/refresh/recovery (B5). Assente se il
+    // Fetta 2b: il lease Live esposto alle route /api/lease, che il bridge
+    // MCP delle celle consuma per register/refresh/recovery. Assente se il
     // lease e' disattivato: le route rispondono 501, non 500.
     ...(leaseManager ? { lease: leaseManager } : {}),
     ...(identityAuthority ? { identityAuthority } : {}),

package/lib/fleet/causes.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// Cause-preserving diagnostics for Fleet up() failures (T4).
+// Cause-preserving diagnostics for Fleet up failures.
 //
 // The up() path of the built-in fleet crosses five boundaries:
 //   1. preflight gates          (command trust, cwd, managed-engine config)

package/lib/fleet/cell-exec.js

@@ -101,7 +101,7 @@ function validIdentity(value) {
 function validLease(value) {
   if (value === undefined) return true;
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  // 2b (A2): la capability statica e' revocata e non esiste piu' nel payload.
+  // 2b: la capability statica e' revocata e non esiste piu' nel payload.
   // Il proof supervisore NON transita qui: arriva sul canale lease dal server.
   if (Object.keys(value).some((k) => !['cellId', 'launchEpoch', 'stablePath'].includes(k))) return false;
   return (value.cellId === undefined || (typeof value.cellId === 'string' && value.cellId.length > 0 && value.cellId.length <= 128))
@@ -134,8 +134,8 @@ function receivePayload(socketPath, nonce, timeoutMs = 5000, opts = {}) {
     const finish = (error, payload) => {
       if (done) return; done = true;
       if (error) { socket.destroy(); reject(error); return; }
-      // R3.1.1 (opt-in): keepOpen restituisce il socket APERTO al caller (broker
-      // lease); il caller lo passa al lease-client. Default: destroy (one-shot).
+      // Opt-in keepOpen: the caller receives the OPEN socket (lease broker)
+      // and passes it to the lease-client. Default: destroy (one-shot).
       if (opts.keepOpen) { resolve({ payload, socket }); return; }
       socket.destroy(); resolve(payload);
     };
@@ -197,7 +197,7 @@ function validIdentityRequest(msg) {
 }
 
 //  schema chiuso del metodo verify (v1). Il proof viene VERIFICATO
-// online dall'authority (C2): il daemon non valuta nulla da solo.
+// Online dall'authority: il daemon non valuta nulla da solo.
 function validVerifyRequest(msg, channelGeneration) {
   if (msg.method !== 'nexuscrew/identity/verify') return false;
   const params = msg.params;
@@ -272,7 +272,7 @@ function createIdentityChannel({
     const reason = outcome && typeof outcome.reason === 'string' ? outcome.reason : 'identity-unverified';
     const code = identityErrorCode(reason);
     sendError(current.rpcId, code, reason);
-    // C7-bis: il canale e' terminato su timeout OLTRE che su revoke — dopo la
+    // Bis: il canale e' terminato su timeout OLTRE che su revoke — dopo la
     // risposta di errore fd4 va in EOF (la TUI vede il canale chiuso).
     if (code === 'REVOKED' || reason === 'timeout') close(code, reason, current.rpcId, false);
   };
@@ -397,7 +397,7 @@ function waitChild(child) {
   });
 }
 
-// Delivery del bootstrap prompt per generazione (0.8.47, R2/R3).
+// Delivery del bootstrap prompt per generazione (0.8.47, /).
 //
 // OWNER UNICO: per gli engine managed Kimi (client 'kimi'/'claude') il
 // supervisore consegna il prompt per TUTTE le generazioni, gen0 compresa —
@@ -408,7 +408,7 @@ function waitChild(child) {
 // massimo una nuova consegna. Engine custom send-keys: contratto legacy
 // invariato (gen0 = runtime.injectPrompt; qui solo gen>0, paste senza Enter).
 //
-// CANCELLAZIONE (R3): cancel() ferma il timer E il polling in volo tramite
+// CANCELLAZIONE: cancel ferma il timer E il polling in volo tramite
 // isCancelled valutato dentro deliverBootstrapPrompt (ogni poll, pre-paste,
 // pre-Enter); il chiamante fa cancel() + await settled prima dello spawn
 // della generazione successiva: zero paste/Enter da un task della generazione
@@ -418,15 +418,15 @@ function waitChild(child) {
 // (solo enum chiusi; l'opzione muore col pane, nessuno state file). Best
 // effort: un set-option fallito lascia up() in report-timeout (onesto), la
 // consegna resta fatta.
-// CANCELLAZIONE (R3+R8): cancel() ferma il timer E il polling in volo tramite
+// CANCELLAZIONE (+): cancel ferma il timer E il polling in volo tramite
 // isCancelled valutato dentro deliverBootstrapPrompt (ogni poll, pre-paste,
 // pre-Enter, post-Enter); il chiamante fa cancel() + await settled prima dello
 // spawn della generazione successiva. cancel() con timer ANCORA PENDENTE
 // (child uscito prima di readyMs, caso early-exit) risolve settled SUBITO:
-// mai deadlock (R8). settled risolve con l'esito della delivery: null se
+// Mai deadlock. settled risolve con l'esito della delivery: null se
 // nessun paste incerto, {state} se la generazione e' terminata con un
 // post-paste incerto (delivery-unknown / staged-not-submitted) — il main loop
-// NON auto-restarta in quel caso (R9: byte potenzialmente residui nel PTY del
+// NON auto-restarta in quel caso (leftover bytes potenzialmente residui nel PTY del
 // pane riusato; fermo bounded + restart operatore).
 function startGenerationPrompt(config, generation, childState, seams = {}) {
   if (!config) return null;
@@ -474,7 +474,7 @@ function startGenerationPrompt(config, generation, childState, seams = {}) {
           const state = result && typeof result.state === 'string' ? result.state : '';
           const uncertain = state === 'delivery-unknown' || state === 'staged-not-submitted';
           if (isCancelled()) {
-            // R9: la generazione e' finita. Propago SOLO gli esiti post-paste
+            // La generazione e' finita. Propago SOLO gli esiti post-paste
             // incerti (residuo PTY possibile); cancelled pre-paste e' pulito.
             return uncertain ? { state } : null;
           }
@@ -482,7 +482,7 @@ function startGenerationPrompt(config, generation, childState, seams = {}) {
             const kind = state === 'skipped-not-ready' && result.notReady ? `:${result.notReady}` : '';
             await markDelivery(`${state}${kind}`);
           }
-          // R12: l'esito post-paste incerto va conservato ANCHE se il child
+          // L'esito post-paste incerto va conservato ANCHE se il child
           // era vivo al ritorno di deliver: i byte possono restare nel PTY del
           // pane e sommarsi al bootstrap della generazione successiva. Al
           // prossimo child exit il main ferma il supervisor (no auto-restart).
@@ -501,7 +501,7 @@ function startGenerationPrompt(config, generation, childState, seams = {}) {
   timer.unref?.();
   return {
     settled,
-    // R8: timer ancora pendente -> settle IMMEDIATO (idempotente): il main
+    // Timer ancora pendente -> settle IMMEDIATO (idempotente): il main
     // loop non resta mai appeso su un child uscito prima di readyMs.
     cancel() {
       cancelled = true;
@@ -542,10 +542,10 @@ async function main(argv = process.argv.slice(2), seams = {}) {
   if (process.env.TMUX) childEnv.TMUX = process.env.TMUX;
   if (process.env.TMUX_PANE) childEnv.TMUX_PANE = process.env.TMUX_PANE;
 
-  // R3.1.2: nessun bearer di lease transita al child. childEnv deriva SOLO da
-  // payload.env (piu' TMUX); payload.lease (cellId/launchEpoch/stablePath) resta
-  // nel supervisore e alimenta il lease-client. spawnImpl passa env + stdio
-  // inherit. Il proof (2b) vive nel lease-client, MAI nell'env del child.
+  // No lease bearer ever reaches the child. childEnv derives ONLY from
+  // payload.env (plus TMUX); payload.lease (cellId/launchEpoch/stablePath) stays
+  // in the supervisor and feeds the lease-client. spawnImpl passes env + stdio
+  // inherit. The proof lives in the lease-client, NEVER in the child env.
   let generation = 0;
   let leaseCtl = null;
   // da revisione interna: current/stopping vivono QUI (prima del lease-client) perche'
@@ -556,9 +556,9 @@ async function main(argv = process.argv.slice(2), seams = {}) {
     leaseCtl = startLeaseClient(leaseSocket, {
       stablePath: payload.lease.stablePath,
       launchEpoch: payload.lease.launchEpoch,
-      // R3.3.4: la generation AVANZA coi restart del supervisore (loop sotto,
-      // generation += 1). Passiamo un getter cosicche' il reconnect presenti
-      // sempre la generation corrente, non 0 fisso (riconcilia :301 con :381).
+      // The generation ADVANCES with supervisor restarts (loop below,
+      // generation += 1). We pass a getter so the reconnect always presents
+      // the current generation, not a fixed 0 (reconciles :301 with :381).
       generation: () => generation,
       onIdentityDown: () => closeIdentityChannel('REVOKED', 'lease unavailable'),
       // da revisione interna: lease persa per tutta la grace senza un
@@ -647,7 +647,7 @@ async function main(argv = process.argv.slice(2), seams = {}) {
           resolve({ code: 1, signal: null, error });
         });
       });
-      // R1: transizione di generazione comunicata al lease PRIMA di aprire il
+      // Transizione di generazione comunicata al lease PRIMA di aprire il
       // canale identita' della generazione nuova. L'exit del figlio ha la
       // precedenza sull'annuncio; FAIL-CLOSED (R1b): solo un annuncio
       // RISOLTO con ok === true E generazione corrispondente apre il canale —
@@ -719,8 +719,8 @@ async function main(argv = process.argv.slice(2), seams = {}) {
       childState.exited = true;
       closeIdentityChannel();
       current = null;
-      // R2/R3: la generazione e' finita. Cancella la delivery in volo e ATTESA
-      // del suo termine PRIMA di qualunque nuovo spawn. R9: se l'esito e' un
+      // : la generazione e' finita. Cancella la delivery in volo e ATTESA
+      // Del suo termine PRIMA di qualunque nuovo spawn.: se l'esito e' un
       // post-paste incerto (delivery-unknown / staged-not-submitted) i byte del
       // prompt possono essere residui nel PTY del pane riusato: NIENTE auto-
       // restart — fermo bounded del supervisor, restart esplicito operatore.

package/lib/fleet/cell-hold.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // lib/fleet/cell-hold.js — placeholder inerte per l'avvio staged del pane Fleet.
-// (NexusCrew 0.8.31 — design piano §3.3: identita tmux sicura)
+// (tmux-safe identity rules: no interactive shell)
 //
 // Resta in attesa finche' `respawn-pane -k` non lo sostituisce con il vero client
 // (cell-exec). Crea il pane e la finestra in modo deterministico cosi' il runtime
@@ -9,11 +9,11 @@
 // cio' impedisce a un child rapido di chiudere la sessione durante il setup. La
 // normalizzazione dei punti nei nomi tmux e gestita separatamente dal mapping v2.
 //
-// Vincoli (piano §3.3): NESSUNA shell interattiva, NESSUN rc/alias/plugin utente,
-// NESSUN dato sensibile, NESSUN argomento interpretato. argv diretto
-// (process.execPath + path assoluto di questo file), puramente bloccante. Non e'
-// il comando reale della cella: command/env/prompt/payload broker non appaiono
-// mai nell'argv tmux.
+// Constraints: NO interactive shell, NO user rc/alias/plugin sourcing,
+// NO sensitive data, NO interpreted arguments. Direct argv
+// (process.execPath + absolute path of this file), purely blocking. It is not
+// the real cell command: command/env/prompt/payload broker never appear
+// in the tmux argv.
 //
 // Uscita silenziosa sul segnale di terminazione inviato da respawn-pane -k.