@mmmbuto/nexuscrew 0.4.2 → 0.7.0

package/lib/fleet/index.js

@@ -0,0 +1,99 @@
+'use strict';
+const fs = require('node:fs');
+const { createFleetExec } = require('./exec.js');
+
+const ENGINES = new Set(['native', 'glm', 'glm-a', 'glm-p', 'ollama', 'ollama-cloud', 'codex-vl']);
+const STATUS_TTL_MS = 2000;
+
+// Trust boundary sul binario (audit F3): regular file, NO symlink,
+// eseguibile dall'owner, NON world-writable.
+function binTrusted(bin) {
+  try {
+    const st = fs.lstatSync(bin);
+    if (!st.isFile()) return false;                 // lstat: un symlink NON è file
+    if (!(st.mode & 0o100)) return false;           // owner-executable
+    if (st.mode & 0o002) return false;              // world-writable
+    return true;
+  } catch (_) { return false; }
+}
+
+function parseStatus(raw) {
+  let d;
+  try { d = JSON.parse(raw); } catch (_) { return null; }
+  if (!d || d.kind !== 'ai-fleet' || d.schemaVersion !== 1 || !Array.isArray(d.cells)) return null;
+  // Strict per cella (audit finale #2): campi obbligatori e tipizzati; una sola
+  // cella malformata invalida l'intero status (fail-closed, feature spenta).
+  const cells = [];
+  for (const c of d.cells) {
+    if (!c || typeof c !== 'object'
+      || typeof c.cell !== 'string' || !c.cell
+      || typeof c.tmuxSession !== 'string' || !c.tmuxSession
+      || typeof c.engine !== 'string' || !c.engine
+      || typeof c.active !== 'boolean' || typeof c.boot !== 'boolean'
+      || typeof c.tmux !== 'boolean'
+      || typeof c.rc !== 'string' || typeof c.key !== 'string') return null;
+    cells.push({
+      cell: c.cell, tmuxSession: c.tmuxSession, engine: c.engine,
+      active: c.active, boot: c.boot, tmux: c.tmux, rc: c.rc, key: c.key,
+      degraded: c.active !== c.tmux,                 // unit e tmux in disaccordo
+    });
+  }
+  return cells;
+}
+
+function httpError(status, msg) { const e = new Error(msg); e.status = status; return e; }
+
+async function createFleet(cfg = {}) {
+  const off = { available: false, isCellSession: () => false };
+  if (cfg.fleetEnabled === false) return off;
+  const bin = cfg.fleetBin;
+  if (!bin || !binTrusted(bin)) return off;
+
+  const fx = createFleetExec(bin);
+  let cells;
+  try { cells = parseStatus(await fx.run(['status', '--json'])); } catch (_) { return off; }
+  if (!cells) return off;                            // schema estraneo → feature spenta
+
+  let cache = { at: Date.now(), cells };
+  const sessions = () => new Set(cache.cells.map((c) => c.tmuxSession));
+
+  async function status() {
+    if (Date.now() - cache.at > STATUS_TTL_MS) {
+      const fresh = parseStatus(await fx.run(['status', '--json']));
+      if (fresh) cache = { at: Date.now(), cells: fresh };
+    }
+    return { available: true, cells: cache.cells };
+  }
+
+  function assertCell(cell) {
+    if (!cache.cells.some((c) => c.cell === cell)) throw httpError(400, `cella sconosciuta: ${cell}`);
+  }
+  function assertEngine(eng) {
+    if (!ENGINES.has(eng)) throw httpError(400, `engine non valido: ${eng}`);
+  }
+  async function cmd(args) {
+    try { await fx.run(args); } catch (e) { throw httpError(502, e.message); }
+    cache = { at: 0, cells: cache.cells };           // invalida: il prossimo status rilegge
+    return { ok: true };
+  }
+
+  return {
+    available: true,
+    status,
+    up: async (cell, { engine, boot } = {}) => {
+      assertCell(cell); if (engine != null) assertEngine(engine);
+      const a = ['up', cell]; if (engine) a.push('--engine', engine); if (boot) a.push('--boot');
+      return cmd(a);
+    },
+    down: async (cell, { boot } = {}) => {
+      assertCell(cell);
+      const a = ['down', cell]; if (boot) a.push('--boot');
+      return cmd(a);
+    },
+    engine: async (cell, eng) => { assertCell(cell); assertEngine(eng); return cmd(['engine', cell, eng]); },
+    boot: async (cell, enabled) => { assertCell(cell); return cmd([enabled ? 'boot' : 'noboot', cell]); },
+    isCellSession: (name) => sessions().has(name),
+  };
+}
+
+module.exports = { createFleet, parseStatus, binTrusted };

package/lib/fleet/routes.js

@@ -0,0 +1,34 @@
+'use strict';
+const express = require('express');
+
+// Router /api/fleet — fleetP è una Promise<Fleet> (createServer non diventa
+// async): ogni handler attende la resolve; unavailable → 404 sui comandi.
+function fleetRoutes(fleetP) {
+  const r = express.Router();
+  r.use(express.json({ limit: '4kb' }));
+
+  const guard = (fn) => async (req, res) => {
+    try {
+      const fleet = await fleetP;
+      if (!fleet.available) return res.status(404).json({ error: 'fleet non disponibile' });
+      res.json(await fn(fleet, req.body || {}));
+    } catch (e) {
+      res.status(e.status || 500).json({ error: String(e.message || e) });
+    }
+  };
+
+  r.get('/status', async (_req, res) => {
+    try {
+      const fleet = await fleetP;
+      if (!fleet.available) return res.json({ available: false });
+      res.json(await fleet.status());
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+  r.post('/up', guard((f, b) => f.up(String(b.cell || ''), { engine: b.engine, boot: !!b.boot })));
+  r.post('/down', guard((f, b) => f.down(String(b.cell || ''), { boot: !!b.boot })));
+  r.post('/engine', guard((f, b) => f.engine(String(b.cell || ''), String(b.engine || ''))));
+  r.post('/boot', guard((f, b) => f.boot(String(b.cell || ''), b.enabled === true)));
+  return r;
+}
+
+module.exports = { fleetRoutes };

package/lib/server.js

@@ -1,15 +1,25 @@
 'use strict';
 const http = require('node:http');
 const path = require('node:path');
+const os = require('node:os');
 const { execFileSync } = require('node:child_process');
 const express = require('express');
 const { WebSocketServer } = require('ws');
-const { defaults, assertLoopback } = require('./config.js');
+const { defaults, loadConfig, assertLoopback } = require('./config.js');
 const { listSessions, attachedClients } = require('./tmux/list.js');
-const { runAction } = require('./tmux/actions.js');
+const { runAction, pasteToSession } = require('./tmux/actions.js');
+const { createSession, killSession, isProtectedSession } = require('./tmux/lifecycle.js');
+const { createPreviewSampler } = require('./tmux/preview.js');
 const { openAttach } = require('./pty/attach.js');
 const { bindWs } = require('./ws/bridge.js');
 const { loadOrCreateToken, verify } = require('./auth/token.js');
+const { requireToken } = require('./auth/middleware.js');
+const { filesRoutes } = require('./files/routes.js');
+const { createOutboxWatcher } = require('./files/watcher.js');
+const VERSION = require('../package.json').version;
+const { transcribe } = require('./voice/transcribe.js');
+const { createFleet } = require('./fleet/index.js');
+const { fleetRoutes } = require('./fleet/routes.js');
 
 function sessionExists(tmuxBin, name) {
   if (typeof name !== 'string' || !/^[\w.@%:+-]{1,128}$/.test(name)) return false;
@@ -18,24 +28,85 @@ function sessionExists(tmuxBin, name) {
 }
 
 function createServer(opts = {}) {
-  const cfg = { ...defaults(), ...opts };
+  const cfg = loadConfig(opts);
   assertLoopback(cfg.bind);
   const token = loadOrCreateToken(cfg.tokenPath);
+  const watcher = createOutboxWatcher({ root: cfg.filesRoot });
+  const previews = createPreviewSampler(cfg.tmuxBin);
+  const attachedWs = new Map(); // ws -> session (per il push dei frame files)
+  const fleetP = createFleet(cfg);                  // async, non blocca il boot
 
   const app = express();
   const distDir = path.join(__dirname, '..', 'frontend', 'dist');
   // no-store on everything (HTML+assets+API): this is a local, token-adjacent tool.
   app.use((_req, res, next) => { res.set('Cache-Control', 'no-store'); next(); });
-  app.get('/api/sessions', async (_req, res) => {
-    try { res.json({ sessions: await listSessions(cfg.tmuxBin) }); }
-    catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+
+  // Tutte le /api dietro Bearer: sul loopback il gate vero è il tunnel,
+  // ma il token chiude anche altri processi locali della stessa macchina.
+  const api = express.Router();
+  api.use(requireToken(token));
+  api.get('/sessions', async (_req, res) => {
+    try {
+      const sessions = await listSessions(cfg.tmuxBin);
+      const sum = watcher.getSummary();
+      const enriched = await Promise.all(sessions.map(async (s) => ({
+        ...s,
+        outbox: sum[s.name] || { count: 0, latest: 0 },
+        preview: await previews.get(s.name),
+      })));
+      res.json({ sessions: enriched });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+  api.post('/sessions', express.json({ limit: '4kb' }), async (req, res) => {
+    try {
+      const { name, cwd, preset } = req.body || {};
+      await createSession(cfg.tmuxBin, { name, cwd, preset },
+        { home: os.homedir(), presets: cfg.sessionPresets });
+      res.status(201).json({ created: true, name });
+    } catch (e) { res.status(e.status || 500).json({ error: String(e.message || e) }); }
   });
-  // Note: the token must never be exposed here.
-  app.get('/api/config', (_req, res) => res.json({ readonlyDefault: cfg.readonlyDefault }));
+  api.delete('/sessions/:name', async (req, res) => {
+    const name = String(req.params.name || '');
+    try {
+      const fleet = await fleetP;
+      if (isProtectedSession(name, fleet.isCellSession)) {
+        return res.status(409).json({ error: 'sessione di cella: usa fleet down' });
+      }
+      const killed = await killSession(cfg.tmuxBin, name);
+      if (!killed) return res.status(404).json({ error: 'sessione inesistente' });
+      res.json({ killed: true });
+    } catch (e) { res.status(e.status || 500).json({ error: String(e.message || e) }); }
+  });
+  api.get('/config', (_req, res) => res.json({
+    readonlyDefault: cfg.readonlyDefault, version: VERSION,
+    bind: cfg.bind, port: cfg.port,
+    presets: ['shell', 'claude', 'codex-vl', 'pi', ...Object.keys(cfg.sessionPresets || {})],
+  }));
+  api.use('/files', filesRoutes({
+    cfg,
+    sessionExists: (name) => sessionExists(cfg.tmuxBin, name),
+    paste: (session, text) => pasteToSession(cfg.tmuxBin, session, text),
+  }));
+  api.use('/fleet', fleetRoutes(fleetP));
+  api.get('/voice/status', (_req, res) => res.json({ serverSttConfigured: !!cfg.voiceUrl }));
+  api.post('/voice/transcribe',
+    express.raw({ type: () => true, limit: '25mb' }),
+    async (req, res) => {
+      try {
+        const out = await transcribe(cfg, req.body, { language: String(req.query.language || 'it') });
+        res.json({ text: out.text || '' });
+      } catch (e) { res.status(e.status || 502).json({ error: e.message }); }
+    });
+  app.use('/api', api);
+
   app.use(express.static(distDir));
   app.get('*', (_req, res) => res.sendFile(path.join(distDir, 'index.html')));
 
   const server = http.createServer(app);
+  // Close the watcher when the HTTP server closes. Registered HERE (inside
+  // createServer) — not in start() — so every createServer consumer is covered,
+  // not only the start() path. watcher.close() is idempotent.
+  server.on('close', () => { watcher.close(); previews.close(); });
   const wss = new WebSocketServer({ server, path: '/ws', maxPayload: 1 << 20 });
   wss.on('connection', (ws) => {
     bindWs(ws, {
@@ -45,10 +116,20 @@ function createServer(opts = {}) {
       runAction: (sess, action) => runAction(cfg.tmuxBin, sess, action),
       countClients: (sess) => attachedClients(cfg.tmuxBin, sess),
       defaults: { readonlyDefault: cfg.readonlyDefault, tmuxBin: cfg.tmuxBin },
+      onAttach: (sess) => attachedWs.set(ws, sess),
     });
+    ws.on('close', () => attachedWs.delete(ws));
+  });
+
+  watcher.on('change', (session, files) => {
+    for (const [client, sess] of attachedWs) {
+      if (sess === session && client.readyState === 1) {
+        try { client.send(JSON.stringify({ type: 'files', session, files })); } catch (_) {}
+      }
+    }
   });
 
-  return { app, server, wss, cfg, token };
+  return { app, server, wss, cfg, token, watcher, fleetP };
 }
 
 function start(opts = {}) {

package/lib/tmux/actions.js

@@ -16,12 +16,74 @@ function actionArgs(name) {
   return Object.prototype.hasOwnProperty.call(ACTIONS, name) ? ACTIONS[name].slice() : null;
 }
 
-// Fire-and-forget: esegue l'azione sulla sessione (match esatto `=name`). false se non allowlistata.
+const SCROLL_LINES = 3;
+
+// Scroll della cronologia via copy-mode: 'up' entra in copy-mode (idempotente
+// se già dentro) e scorre; con -e il ritorno in fondo ESCE da copy-mode da
+// solo, quindi il gesto "trascina giù fino in fondo" riporta al vivo.
+function scrollArgs(session, dir) {
+  if (typeof session !== 'string') return null;
+  if (dir !== 'up' && dir !== 'down') return null;
+  const target = `=${session}:`;
+  return [
+    ['copy-mode', '-e', '-t', target],
+    ['send-keys', '-t', target, '-X', '-N', String(SCROLL_LINES), dir === 'up' ? 'scroll-up' : 'scroll-down'],
+  ];
+}
+
+function runScroll(tmuxBin, session, dir) {
+  const steps = scrollArgs(session, dir);
+  if (!steps) return false;
+  try {
+    // send-keys -X vale solo in copy-mode: va in sequenza, non in parallelo.
+    execFile(tmuxBin, steps[0], () => { execFile(tmuxBin, steps[1], () => {}); });
+    return true;
+  } catch (_) { return false; }
+}
+
+// Fire-and-forget: esegue l'azione sulla sessione. Target `=name:` (exact-match
+// + colon): su tmux 3.4 il bare `=name` fallisce per i comandi pane/window-target.
 function runAction(tmuxBin, session, name) {
+  if (name === 'scroll-up') return runScroll(tmuxBin, session, 'up');
+  if (name === 'scroll-down') return runScroll(tmuxBin, session, 'down');
   const base = actionArgs(name);
   if (!base) return false;
-  try { execFile(tmuxBin, [...base, '-t', `=${session}`], () => {}); return true; }
+  try { execFile(tmuxBin, [...base, '-t', `=${session}:`], () => {}); return true; }
   catch (_) { return false; }
 }
 
-module.exports = { actionArgs, runAction, ACTIONS };
+const MAX_PASTE = 4096;
+
+// true se text contiene control char (codici 0x00-0x1f e 0x7f). Espresso via
+// charCode invece di regex perche' il write-layer corrompe gli escape backslash
+// nel sorgente (v. NOTE in lib/files/store.js).
+function hasControlChar(text) {
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text.charCodeAt(i);
+    if (c <= 0x1f || c === 0x7f) return true;
+  }
+  return false;
+}
+
+// Digita testo literal nella sessione, SENZA Invio: il '--' protegge testi
+// che iniziano con '-'; i control char (inclusi i ritorni a capo CR e LF)
+// sono rifiutati a monte così un paste non può mai submitare un prompt.
+function pasteArgs(session, text) {
+  if (typeof session !== 'string' || typeof text !== 'string') return null;
+  if (!text || text.length > MAX_PASTE) return null;
+  if (hasControlChar(text)) return null;
+  return ['send-keys', '-t', `=${session}:`, '-l', '--', text];
+}
+
+// Risolve col VERO esito di tmux (l'exit code), non col solo lancio del
+// processo: un target inesistente deve produrre pasted:false, non un falso ok.
+function pasteToSession(tmuxBin, session, text) {
+  const args = pasteArgs(session, text);
+  if (!args) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    try { execFile(tmuxBin, args, (err) => resolve(!err)); }
+    catch (_) { resolve(false); }
+  });
+}
+
+module.exports = { actionArgs, runAction, ACTIONS, pasteArgs, pasteToSession, scrollArgs };

package/lib/tmux/lifecycle.js

@@ -0,0 +1,86 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+
+// Preset allowlistati (audit F1): il client sceglie un NOME, mai un comando.
+// Estendibili da config.json `sessionPresets` (name -> array argv di stringhe).
+const PRESETS = { shell: null, claude: ['claude'], 'codex-vl': ['codex-vl'], pi: ['pi'] };
+
+const NAME_RE = /^[\w.-]{1,64}$/;
+function validSessionName(name) {
+  return typeof name === 'string' && NAME_RE.test(name) && !name.startsWith('-');
+}
+
+// cwd reale sotto la home reale (audit F1): realpath su ENTRAMBI, così un
+// symlink dentro home che punta fuori viene rifiutato.
+function resolveCwd(cwd, home) {
+  try {
+    const real = fs.realpathSync(cwd);
+    const realHome = fs.realpathSync(home);
+    if (!fs.statSync(real).isDirectory()) return null;
+    if (real !== realHome && !real.startsWith(realHome + path.sep)) return null;
+    return real;
+  } catch (_) { return null; }
+}
+
+// Denylist kill INDIPENDENTE dal registry (audit F2): qualunque cloud-* è
+// protetta anche con fleet assente/rotto; in più le tmuxSession del registry.
+function isProtectedSession(name, isCellSession) {
+  if (/^cloud-/i.test(String(name))) return true;
+  try { return !!isCellSession(name); } catch (_) { return false; }
+}
+
+function presetArgv(preset, extra) {
+  const table = { ...PRESETS };
+  for (const [k, v] of Object.entries(extra || {})) {
+    if (NAME_RE.test(k) && Array.isArray(v) && v.every((s) => typeof s === 'string')) table[k] = v;
+  }
+  if (!Object.prototype.hasOwnProperty.call(table, preset)) return undefined;
+  return table[preset];
+}
+
+// Pure: argomenti tmux per la create, o null se input invalido.
+function buildCreateArgs(name, realCwd, preset, extraPresets) {
+  if (!validSessionName(name) || typeof realCwd !== 'string' || !realCwd) return null;
+  const argv = presetArgv(String(preset || 'shell'), extraPresets);
+  if (argv === undefined) return null;
+  const base = ['new-session', '-d', '-s', name, '-c', realCwd];
+  return argv ? [...base, ...argv] : base;
+}
+
+function httpError(status, msg) { const e = new Error(msg); e.status = status; return e; }
+
+function createSession(tmuxBin, { name, cwd, preset }, { home, presets } = {}) {
+  return new Promise((resolve, reject) => {
+    if (!validSessionName(name)) return reject(httpError(400, 'nome sessione non valido'));
+    // Il namespace cloud-* e' delle celle fleet (audit finale #1): una generica
+    // con quel prefisso occuperebbe il binding per-nome e sarebbe poi 409 al kill.
+    if (/^cloud-/i.test(name)) return reject(httpError(409, 'namespace riservato alle celle (cloud-*): usa fleet up'));
+    const real = resolveCwd(String(cwd || home), home);
+    if (!real) return reject(httpError(400, 'cwd non valida (deve esistere sotto la home)'));
+    const args = buildCreateArgs(name, real, preset, presets);
+    if (!args) return reject(httpError(400, 'preset non in allowlist'));
+    execFile(tmuxBin, args, (err, _o, stderr) => {
+      if (err) {
+        if (/duplicate session/i.test(stderr || '')) return reject(httpError(409, 'sessione già esistente'));
+        return reject(httpError(500, `tmux new-session failed: ${String(stderr || err.message).trim()}`));
+      }
+      resolve();
+    });
+  });
+}
+
+function killSession(tmuxBin, name) {
+  return new Promise((resolve, reject) => {
+    execFile(tmuxBin, ['kill-session', '-t', `=${name}`], (err, _o, stderr) => {
+      if (err) {
+        if (/can't find session|no server running/i.test(stderr || '')) return resolve(false);
+        return reject(httpError(500, `tmux kill-session failed: ${String(stderr || err.message).trim()}`));
+      }
+      resolve(true);
+    });
+  });
+}
+
+module.exports = { PRESETS, validSessionName, resolveCwd, isProtectedSession, buildCreateArgs, createSession, killSession };

package/lib/tmux/list.js

@@ -1,19 +1,21 @@
 'use strict';
 const { execFile, execFileSync } = require('node:child_process');
 
-const FMT = "#{session_name}\t#{session_attached}\t#{session_windows}\t#{session_created}";
+const FMT = "#{session_name}\t#{session_attached}\t#{session_windows}\t#{session_created}\t#{session_activity}\t#{pane_current_command}";
 
 function parseSessions(raw) {
   return String(raw)
     .split('\n')
     .filter((l) => l.trim() !== '')
     .map((line) => {
-      const [name, attached, windows, created] = line.split('\t');
+      const [name, attached, windows, created, activity, cmd] = line.split('\t');
       return {
         name,
         attached: attached === '1',
         windows: Number(windows),
         created: Number(created),
+        activity: Number(activity) || 0,
+        cmd: cmd || '',
       };
     });
 }

package/lib/tmux/preview.js

@@ -0,0 +1,73 @@
+'use strict';
+const { execFile } = require('node:child_process');
+
+const MAX_LEN = 240;
+
+// Strip ANSI (CSI/OSC) e control char via charCode — niente escape regex nel
+// sorgente (v. NOTE in lib/files/store.js sul write-layer).
+function sanitizePreview(raw) {
+  if (typeof raw !== 'string') return '';
+  let out = '';
+  let i = 0;
+  while (i < raw.length && out.length < MAX_LEN + 1) {
+    const c = raw.charCodeAt(i);
+    if (c === 0x1b) {                                   // ESC: salta la sequenza
+      const n = raw.charCodeAt(i + 1);
+      if (n === 0x5b) {                                 // CSI: fino a byte finale 0x40-0x7e
+        i += 2; while (i < raw.length && (raw.charCodeAt(i) < 0x40 || raw.charCodeAt(i) > 0x7e)) i += 1;
+        i += 1; continue;
+      }
+      if (n === 0x5d) {                                 // OSC: fino a BEL o ESC\
+        i += 2; while (i < raw.length && raw.charCodeAt(i) !== 0x07 && raw.charCodeAt(i) !== 0x1b) i += 1;
+        i += (raw.charCodeAt(i) === 0x1b) ? 2 : 1; continue;
+      }
+      i += 2; continue;                                 // altre ESC-seq corte
+    }
+    if (c <= 0x1f || c === 0x7f) { i += 1; continue; }  // control char
+    out += raw[i]; i += 1;
+  }
+  return out.trim().slice(0, MAX_LEN);
+}
+
+// Sampler con cache per sessione, concorrenza limitata e timeout: la preview è
+// best-effort — errori → null, MAI nel log (audit F7).
+function createPreviewSampler(tmuxBin, { ttlMs = 3000, timeoutMs = 1500, maxConcurrent = 4 } = {}) {
+  const cache = new Map();        // session -> {at, value}
+  let inFlight = 0;
+  const waiters = [];
+
+  const acquire = () => new Promise((res) => {
+    if (inFlight < maxConcurrent) { inFlight += 1; res(); } else waiters.push(res);
+  });
+  const release = () => { inFlight -= 1; const w = waiters.shift(); if (w) { inFlight += 1; w(); } };
+
+  function capture(session) {
+    return new Promise((resolve) => {
+      execFile(tmuxBin, ['capture-pane', '-p', '-t', `=${session}:`], { timeout: timeoutMs, killSignal: 'SIGKILL' },
+        (err, stdout) => {
+          if (err) return resolve(null);
+          const lines = String(stdout).split('\n');
+          for (let i = lines.length - 1; i >= 0; i -= 1) {
+            const s = sanitizePreview(lines[i]);
+            if (s) return resolve(s);
+          }
+          resolve('');
+        });
+    });
+  }
+
+  async function get(session) {
+    const hit = cache.get(session);
+    if (hit && Date.now() - hit.at < ttlMs) return hit.value;
+    await acquire();
+    try {
+      const value = await capture(session);
+      cache.set(session, { at: Date.now(), value });
+      return value;
+    } finally { release(); }
+  }
+
+  return { get, close: () => cache.clear() };
+}
+
+module.exports = { sanitizePreview, createPreviewSampler };

package/lib/voice/transcribe.js

@@ -0,0 +1,41 @@
+'use strict';
+// Voice STT proxy (graceful). voiceUrl null => non configurato: 503 pulito, non 502.
+// Web Speech nel browser resta indipendente da questo proxy (split model M5).
+const fs = require('node:fs');
+
+function loadVoiceToken(cfg) {
+  if (cfg.voiceToken) return cfg.voiceToken;
+  if (!cfg.voiceTokenFile) return null; // null = non configurato (no readFileSync)
+  try {
+    const t = fs.readFileSync(cfg.voiceTokenFile, 'utf8').trim();
+    return t || null;
+  } catch (_) { return null; }
+}
+
+function httpError(status, message) {
+  return Object.assign(new Error(message), { status });
+}
+
+// Config-only: true se voiceUrl valorizzato (no reachability check nel primo giro).
+function serverSttConfigured(cfg) {
+  return !!cfg.voiceUrl;
+}
+
+async function transcribe(cfg, audioBuffer, { language = 'it', fetchImpl = fetch } = {}) {
+  if (!audioBuffer || audioBuffer.length === 0) throw httpError(400, 'audio mancante');
+  if (!cfg.voiceUrl) throw httpError(503, 'server STT not configured'); // graceful, non 502
+  const token = loadVoiceToken(cfg);
+  if (!token) throw httpError(502, 'STT non disponibile (token voice mancante)');
+  let r;
+  try {
+    r = await fetchImpl(`${cfg.voiceUrl}/v1/audio/transcriptions`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+      body: JSON.stringify({ file: audioBuffer.toString('base64'), language }),
+    });
+  } catch (_) { throw httpError(502, 'STT non disponibile (mcp-voice giù)'); }
+  if (!r.ok) throw httpError(502, `STT errore upstream (${r.status})`);
+  return r.json();
+}
+
+module.exports = { loadVoiceToken, transcribe, serverSttConfigured };

package/lib/ws/bridge.js

@@ -11,7 +11,7 @@ function clamp(n, lo, hi, def) {
 }
 
 function bindWs(ws, deps) {
-  const { openAttach, verifyToken, isValidSession = () => true, runAction = () => false, countClients = () => 0, defaults = {} } = deps;
+  const { openAttach, verifyToken, isValidSession = () => true, runAction = () => false, countClients = () => 0, defaults = {}, onAttach = () => {} } = deps;
   let pty = null;
   let attached = false;
   let session = null;
@@ -31,6 +31,7 @@ function bindWs(ws, deps) {
       if (!isValidSession(msg.session)) return fail(4404, 'no such session');
       attached = true;
       session = msg.session;
+      onAttach(session, ws);
       // Resize default: when nobody else is attached, drive the session size so a
       // small phone gets a usable (non-clipped) view and clean line editing. When a
       // real terminal is already attached, default to ignore-size so we don't shrink

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.4.2",
+  "version": "0.7.0",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {
@@ -15,19 +15,20 @@
     "README.md"
   ],
   "scripts": {
-    "start": "node bin/nexuscrew.js",
-    "dev": "node bin/nexuscrew.js",
+    "start": "node bin/nexuscrew.js serve",
+    "dev": "node bin/nexuscrew.js serve",
     "build": "cd frontend && npm install && npm run build && cd ..",
     "test": "node --test tests/*.test.js"
   },
   "dependencies": {
+    "@mmmbuto/pty-termux-utils": "^1.1.4",
     "express": "^4.21.0",
-    "ws": "^8.18.0",
-    "@mmmbuto/pty-termux-utils": "^1.1.4"
+    "multer": "^2.2.0",
+    "ws": "^8.18.0"
   },
   "optionalDependencies": {
-    "node-pty": "^1.1.0",
-    "@lydell/node-pty-linux-x64": "^1.2.0-beta.12"
+    "@lydell/node-pty-linux-x64": "^1.2.0-beta.12",
+    "node-pty": "^1.1.0"
   },
   "engines": {
     "node": ">=18"
@@ -56,5 +57,8 @@
     "url": "https://github.com/DioNanos/nexuscrew"
   },
   "author": "DioNanos",
-  "license": "MIT"
+  "license": "MIT",
+  "allowScripts": {
+    "@mmmbuto/node-pty-android-arm64@1.1.0": true
+  }
 }