npm - @mmmbuto/nexuscrew - Versions diffs - 0.8.26 → 0.8.28 - Mend

@mmmbuto/nexuscrew 0.8.26 → 0.8.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/CHANGELOG.md +46 -0
package/README.md +44 -9
package/frontend/dist/assets/{index-DqG-mDnV.css → index-BAzlX2nP.css} +1 -1
package/frontend/dist/assets/index-DiKMLCvW.js +93 -0
package/frontend/dist/index.html +2 -2
package/frontend/dist/version.json +1 -1
package/lib/cli/commands.js +19 -2
package/lib/cli/doctor.js +166 -1
package/lib/cli/service.js +10 -5
package/lib/diagnostics/routes.js +43 -0
package/lib/diagnostics/store.js +139 -0
package/lib/fleet/builtin.js +201 -16
package/lib/fleet/causes.js +68 -0
package/lib/fleet/cell-exec.js +17 -2
package/lib/fleet/definitions.js +86 -4
package/lib/fleet/launch.js +19 -1
package/lib/fleet/managed.js +73 -12
package/lib/fleet/routes.js +44 -5
package/lib/fleet/runtime.js +69 -33
package/lib/nodes/aliases.js +122 -0
package/lib/proxy/federation.js +26 -2
package/lib/runtime/env.js +60 -1
package/lib/server.js +28 -5
package/lib/settings/routes.js +32 -0
package/lib/update/manager.js +8 -0
package/package.json +1 -1
package/frontend/dist/assets/index-DkIPrmX6.js +0 -91

package/frontend/dist/index.html CHANGED Viewed

@@ -11,8 +11,8 @@
   <meta name="apple-mobile-web-app-title" content="NexusCrew" />
   <link rel="manifest" href="/manifest.json" />
   <title>NexusCrew</title>
-  <script type="module" crossorigin src="/assets/index-DkIPrmX6.js"></script>
-  <link rel="stylesheet" crossorigin href="/assets/index-DqG-mDnV.css">
+  <script type="module" crossorigin src="/assets/index-DiKMLCvW.js"></script>
+  <link rel="stylesheet" crossorigin href="/assets/index-BAzlX2nP.css">
 </head>
 <body>
   <div id="root"></div>

package/frontend/dist/version.json CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":"0.8.26"}
1	+ {"version":"0.8.28"}

package/lib/cli/commands.js CHANGED Viewed

@@ -14,7 +14,7 @@ const pidf = require('./pidfile.js');
 const { runInit, ensureFleetDefaults } = require('./init.js');
 const { rotateToken } = require('../auth/token.js');
 const urlmod = require('./url.js');
-const { doctor } = require('./doctor.js');
+const { doctor, checkServiceWorkingDirectory } = require('./doctor.js');
 const nodesStore = require('../nodes/store.js');
 const nodesTunnel = require('../nodes/tunnel.js');
 const nodesCmds = require('../nodes/commands.js');
@@ -346,6 +346,11 @@ function servicePinsLegacyPort(platform, home, installPath) {
   try { return /NEXUSCREW_PORT/.test(fs.readFileSync(target, 'utf8')); } catch (_) { return false; }
 }
+function serviceDefinitionNeedsRefresh(platform, home, installPath) {
+  if (servicePinsLegacyPort(platform, home, installPath)) return true;
+  return !checkServiceWorkingDirectory(platform, home, installPath).ok;
+}
 function portAvailable(port, host = '127.0.0.1') {
   return new Promise((resolve) => {
     const s = net.createServer();
@@ -465,8 +470,19 @@ async function smartUp(opts = {}) {
   // config.json forever. Regenerate once so config.json becomes authoritative.
   const home = opts.home || require('node:os').homedir();
   const persistent = bootState({ ...opts, platform }).enabled;
-  if (persistent && servicePinsLegacyPort(platform, home, opts.installPath)) {
+  let serviceRefreshed = false;
+  if (persistent && serviceDefinitionNeedsRefresh(platform, home, opts.installPath)) {
     runInitImpl({ ...opts, log: quiet, platform, installBoot: true, printUrl: false });
+    serviceRefreshed = checkServiceWorkingDirectory(platform, home, opts.installPath).ok;
+    // Termux:Boot has no service manager, so replacing the script alone cannot
+    // change the cwd of the already-running pidfile owner. Restart exactly once
+    // after a verified migration; Linux/macOS are restarted by installService.
+    if (serviceRefreshed && platform === 'termux') {
+      const migrated = restartImpl({ ...opts, platform, log: quiet });
+      if (!migrated || migrated.restarted !== true) {
+        throw new Error(`service cwd migration restart failed: ${(migrated && migrated.reason) || 'unknown'}`);
+      }
+    }
   }
   if (!port) port = urlmod.loadPort(opts);
@@ -972,6 +988,7 @@ function dispatch(argv, opts = {}) {
 module.exports = {
   dispatch, dispatchNodes, serve, start, stop, status, parseFlags, HELP, NODES_HELP,
   smartUp, url, tokenRotate, logs, doctor, update, restart,
+  serviceDefinitionNeedsRefresh,
   portAvailable, findAvailablePort, probeNexusCrew, waitForNexusCrew, openPwa, startPortable, wizardComplete,
   servicePinsLegacyPort,
   isServiceRunning, readRoles,

package/lib/cli/doctor.js CHANGED Viewed

@@ -14,6 +14,9 @@ const { installPath } = require('./service.js');
 const { resolvePaths } = require('./url.js');
 const { commandExists } = require('./path.js');
 const { loadDefinitions } = require('../fleet/definitions.js');
+const {
+  termuxRuntimePaths, trustedTermuxPreload, TERMUX_EXEC_BASENAME_RE,
+} = require('../runtime/env.js');
 function nodeMajor() {
   return parseInt(String(process.versions.node).split('.')[0], 10);
@@ -64,6 +67,65 @@ function checkService(platform, home, execImpl, uidVal, installPathOverride) {
   };
 }
+function decodeXmlText(value) {
+  return String(value)
+    .replace(/&quot;/g, '"')
+    .replace(/&gt;/g, '>')
+    .replace(/&lt;/g, '<')
+    .replace(/&amp;/g, '&');
+}
+function checkMacServiceWorkingDirectory(platform, home, installPathOverride) {
+  if (platform !== 'mac') {
+    return { name: 'launchd cwd stabile', ok: true, detail: `${platform}: non applicabile` };
+  }
+  return checkServiceWorkingDirectory(platform, home, installPathOverride);
+}
+// The service cwd is inherited by a shared tmux server and every future pane.
+// It must therefore be HOME, never the replaceable runtime directory. This
+// check reads only the installed definition and fails closed on missing,
+// symlinked, malformed, or legacy service files.
+function checkServiceWorkingDirectory(platform, home, installPathOverride) {
+  if (!['linux', 'mac', 'termux'].includes(platform)) {
+    return { name: 'service cwd stabile', ok: true, detail: `${platform}: non applicabile` };
+  }
+  const target = installPathOverride || installPath(platform, home);
+  let raw;
+  try {
+    const st = fs.lstatSync(target);
+    if (st.isSymbolicLink() || !st.isFile()) throw Object.assign(new Error('definizione service non regolare'), { code: 'UNSAFE' });
+    raw = fs.readFileSync(target, 'utf8');
+  }
+  catch (error) {
+    return {
+      name: 'service cwd stabile', ok: false,
+      detail: error.code === 'ENOENT' ? `service non installato (${target})` : error.message,
+    };
+  }
+  let actual = '';
+  let ok = false;
+  if (platform === 'mac') {
+    const match = raw.match(/<key>WorkingDirectory<\/key>\s*<string>([\s\S]*?)<\/string>/);
+    if (!match) return { name: 'service cwd stabile', ok: false, detail: 'WorkingDirectory assente dal plist' };
+    actual = decodeXmlText(match[1]);
+    ok = actual === String(home);
+  } else if (platform === 'linux') {
+    const match = raw.match(/^WorkingDirectory=(.+)$/m);
+    if (!match) return { name: 'service cwd stabile', ok: false, detail: 'WorkingDirectory assente dalla unit' };
+    actual = match[1].replace(/%%/g, '%');
+    ok = actual === String(home);
+  } else {
+    const stable = /^\s*cd -- "\$HOME"\s*$/m.test(raw);
+    actual = stable ? '$HOME' : (/^\s*cd\s+--\s+(.+)$/m.exec(raw)?.[1] || 'cd assente');
+    ok = stable;
+  }
+  return {
+    name: 'service cwd stabile', ok,
+    detail: ok ? (platform === 'termux' ? '$HOME' : String(home)) : `${actual} (atteso HOME stabile)`,
+  };
+}
 function checkBoot(platform, home, execImpl) {
   if (platform === 'termux') {
     const p = path.join(home, '.termux', 'boot', 'nexuscrew.sh');
@@ -186,6 +248,102 @@ function checkTokenPerms(tokenPath) {
   }
 }
+// Presence-only Termux preload check. On the Google Play build of Termux
+// (targetSdk >= 29, SELinux `untrusted_app` domain) every command pane spawned
+// by the shared tmux server dies at execve() unless libtermux-exec is
+// preloaded. The validated preload is preserved by minimalRuntimeEnv; this
+// check tells the user, BEFORE launching a cell, whether the trusted library
+// exists under PREFIX/lib and whether the current process carries a trusted
+// LD_PRELOAD. It is strictly read-only: no tmux socket is touched, no service
+// or device state is mutated, no command is spawned.
+function checkTermuxExec(runtimeEnv, opts = {}) {
+  const env = runtimeEnv || process.env;
+  const platform = opts.platform || detectPlatform();
+  const termux = termuxRuntimePaths(env, { platform, home: opts.home });
+  if (!termux) {
+    return { name: 'termux-exec preload', ok: true, detail: `${platform}: non applicabile` };
+  }
+  const trusted = trustedTermuxPreload(env, { platform, home: opts.home });
+  const libDir = path.join(termux.prefix, 'lib');
+  let present = '';
+  let candidates = [];
+  try {
+    candidates = fs.readdirSync(libDir).filter((name) => TERMUX_EXEC_BASENAME_RE.test(name)).sort();
+  } catch (_) { /* absent/unreadable */ }
+  for (const name of candidates) {
+    const candidate = path.join(libDir, name);
+    try { if (fs.statSync(candidate).isFile()) { present = candidate; break; } } catch (_) { /* next */ }
+  }
+  if (trusted) {
+    return { name: 'termux-exec preload', ok: true, detail: `preload trusted: ${path.basename(trusted)}` };
+  }
+  if (present) {
+    return {
+      name: 'termux-exec preload', ok: true, warn: true,
+      detail: `libreria presente (${path.basename(present)}) ma LD_PRELOAD non valido nell'env del doctor: avvia il servizio da una shell Termux di login o via termux-exec preload`,
+    };
+  }
+  return {
+    name: 'termux-exec preload', ok: false,
+    detail: 'libtermux-exec non trovata sotto PREFIX/lib: sulla build Google Play celle e shell non possono eseguire comandi',
+  };
+}
+// Read-only probe of the long-lived tmux server cwd. A server that retained an
+// unlinked runtime directory keeps accepting clients but makes later children
+// fail getcwd(3). Never reports the path itself; only stable state.
+function checkTmuxServerCwd(platform, execImpl, opts = {}) {
+  if (!['linux', 'termux'].includes(platform)) {
+    return { name: 'tmux server cwd', ok: true, detail: `${platform}: non applicabile` };
+  }
+  let rawPid = '';
+  try {
+    rawPid = String(execImpl(opts.tmuxBin || 'tmux', ['display-message', '-p', '#{pid}'], { encoding: 'utf8' }) || '').trim();
+  } catch (_) {
+    return { name: 'tmux server cwd', ok: true, warn: true, detail: 'server tmux non attivo; probe rinviato al primo avvio' };
+  }
+  if (!/^\d+$/.test(rawPid)) {
+    return { name: 'tmux server cwd', ok: true, warn: true, detail: 'server tmux non rilevato' };
+  }
+  try {
+    const resolveImpl = opts.procCwdImpl || ((pid) => fs.realpathSync(`/proc/${pid}/cwd`));
+    const cwd = resolveImpl(Number(rawPid));
+    if (typeof cwd !== 'string' || !cwd) throw new Error('cwd vuota');
+    return { name: 'tmux server cwd', ok: true, detail: 'cwd risolvibile' };
+  } catch (_) {
+    return {
+      name: 'tmux server cwd', ok: false,
+      detail: 'cwd del server tmux non risolvibile (directory sostituita); termina le sessioni in modo esplicito e riavvia tmux',
+    };
+  }
+}
+// Inspect only the single tmux global environment key required by
+// termux-exec. The value is validated and then discarded; it is never logged.
+// This distinguishes a healthy server from RC-2 (stale/no preload) and RC-7
+// (present but rejected by the trust boundary) without killing any session.
+function checkTmuxServerTermuxPreload(runtimeEnv, execImpl, opts = {}) {
+  const env = runtimeEnv || process.env;
+  const platform = opts.platform || detectPlatform();
+  if (!termuxRuntimePaths(env, { platform, home: opts.home })) {
+    return { name: 'tmux server termux-exec', ok: true, detail: `${platform}: non applicabile` };
+  }
+  let raw = '';
+  try {
+    raw = String(execImpl(opts.tmuxBin || 'tmux', ['show-environment', '-g', 'LD_PRELOAD'], { encoding: 'utf8' }) || '').trim();
+  } catch (_) {
+    return { name: 'tmux server termux-exec', ok: true, warn: true, detail: 'server tmux non attivo; probe rinviato al primo avvio' };
+  }
+  const match = raw.match(/^LD_PRELOAD=(.+)$/);
+  const trusted = match && trustedTermuxPreload({ ...env, LD_PRELOAD: match[1] }, { platform, home: opts.home });
+  return trusted
+    ? { name: 'tmux server termux-exec', ok: true, detail: 'preload trusted presente nel server tmux' }
+    : {
+      name: 'tmux server termux-exec', ok: false,
+      detail: 'LD_PRELOAD assente o non trusted nel server tmux; server stale o formato non compatibile (nessun kill automatico)',
+    };
+}
 // Check MCP identity (P0). NON-FAILING per costrutto: `ok` è sempre true, così
 // chi usa NexusCrew solo come PWA (nessuna integrazione MCP) non vede mai il
 // doctor andare in FAIL solo per env MCP assente. Il check osserva SOLO la
@@ -266,15 +424,19 @@ function doctor(opts = {}) {
     checkTmux(existsImpl, opts.tmuxBin),
     checkPty(ptyLoad),
     checkService(platform, home, execImpl, uidVal, opts.installPath),
+    checkServiceWorkingDirectory(platform, home, opts.installPath),
     checkBoot(platform, home, execImpl),
     checkUserLinger(platform, execImpl, uidVal),
     checkTmuxSurvival(platform, execImpl),
     checkTokenPerms(tokenPath),
     checkFleetDefinitions(home, opts.fleetDefsPath, fleetEnabled),
+    checkTermuxExec(opts.env, { platform, home }),
     checkSshClient(existsImpl),
     checkAutossh(existsImpl),
     checkSshPermitlisten(opts.sshVersion),
     checkMcpIdentity(opts.env),
+    checkTmuxServerCwd(platform, execImpl, { tmuxBin: opts.tmuxBin, procCwdImpl: opts.procCwdImpl }),
+    checkTmuxServerTermuxPreload(opts.env, execImpl, { platform, home, tmuxBin: opts.tmuxBin }),
   ];
   for (const c of checks) {
@@ -289,8 +451,11 @@ function doctor(opts = {}) {
 module.exports = {
   doctor, nodeMajor,
   checkNode, checkTmux, checkPty, checkService, checkBoot, checkTokenPerms,
+  checkMacServiceWorkingDirectory,
   checkFleetDefinitions,
+  checkServiceWorkingDirectory,
   checkTmuxSurvival, checkUserLinger,
   checkSshClient, checkAutossh, checkSshPermitlisten,
-  checkMcpIdentity,
+  checkMcpIdentity, checkTermuxExec,
+  checkTmuxServerCwd, checkTmuxServerTermuxPreload,
 };

package/lib/cli/service.js CHANGED Viewed

@@ -59,9 +59,12 @@ function generateService(platform, ctx) {
 function generateLinux(ctx) {
   assertSystemdSafe('repoRoot', ctx.repoRoot); // [M3] reject char non gestibili
   assertSystemdSafe('nodeBin', ctx.nodeBin);
-  const workDir = ctx.runtimeDir || path.join(ctx.home, '.nexuscrew');
-  assertSystemdSafe('runtimeDir', workDir);
-  const runtime = escapeSystemdPath(workDir);
+  // HOME is stable across init/repair/update. The runtime directory may be
+  // atomically replaced; keeping it as the service cwd leaves the HTTP process
+  // and a shared tmux server holding an orphaned inode, so every later pane can
+  // fail getcwd(3). Runtime state still lives in runtimeDir; only cwd changes.
+  assertSystemdSafe('home', ctx.home);
+  const runtime = escapeSystemdPath(ctx.home);
   const node = escapeSystemdExec(ctx.nodeBin);
   const repoBin = escapeSystemdExec(path.join(ctx.repoRoot, 'bin', 'nexuscrew.js'));
   const nodeDir = escapeSystemdPath(path.dirname(ctx.nodeBin));
@@ -90,7 +93,9 @@ WantedBy=default.target
 function generateMac(ctx) {
   const nodeXml = escapeXml(ctx.nodeBin);
   const repoBinXml = escapeXml(path.join(ctx.repoRoot, 'bin', 'nexuscrew.js'));
-  const runtimeXml = escapeXml(ctx.runtimeDir || path.join(ctx.home, '.nexuscrew'));
+  // HOME remains stable when init or repair atomically replaces the runtime
+  // directory; launchd must not retain an unlinked runtime-directory cwd.
+  const runtimeXml = escapeXml(ctx.home);
   const homeXml = escapeXml(ctx.home);
   const launchPath = [...new Set([
     path.dirname(ctx.nodeBin), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin',
@@ -149,7 +154,7 @@ export LANG=\${LANG:-en_US.UTF-8}
 export LC_CTYPE=\${LC_CTYPE:-en_US.UTF-8}
 termux-wake-lock 2>/dev/null || true
 mkdir -p "$HOME/.nexuscrew" "$TMPDIR" "$TMUX_TMPDIR"
-cd -- "$HOME/.nexuscrew"
+cd -- "$HOME"
 exec ${nodeQ} ${repoBinQ} serve --pidfile >> "$HOME/.nexuscrew/nexuscrew.log" 2>&1
 `;
 }

package/lib/diagnostics/routes.js ADDED Viewed

@@ -0,0 +1,43 @@
+'use strict';
+const express = require('express');
+function diagnosticsRoutes({ diagnostics, readonly = () => false } = {}) {
+  if (!diagnostics) throw new Error('diagnostics store required');
+  const router = express.Router();
+  router.use(express.json({ limit: '2kb' }));
+  const mutGate = (_req, res, next) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: mutazione diagnostica bloccata' });
+    next();
+  };
+  router.get('/status', (_req, res) => res.json(diagnostics.status()));
+  router.get('/logs', (req, res) => {
+    try {
+      const keys = Object.keys(req.query || {});
+      if (keys.some((key) => !['after', 'limit'].includes(key))) return res.status(400).json({ error: 'query non valida' });
+      const after = req.query.after === undefined ? 0 : Number(req.query.after);
+      const limit = req.query.limit === undefined ? 200 : Number(req.query.limit);
+      res.json(diagnostics.logs({ after, limit }));
+    } catch (error) { res.status(400).json({ error: String(error.message || error) }); }
+  });
+  router.patch('/verbose', mutGate, (req, res) => {
+    try {
+      const body = req.body;
+      if (!body || typeof body !== 'object' || Array.isArray(body)
+        || Object.keys(body).some((key) => !['enabled', 'durationSeconds'].includes(key))) {
+        return res.status(400).json({ error: 'body non valido' });
+      }
+      res.json(diagnostics.setVerbose(body.enabled, body.durationSeconds === undefined ? 900 : body.durationSeconds));
+    } catch (error) { res.status(400).json({ error: String(error.message || error) }); }
+  });
+  router.delete('/logs', mutGate, (_req, res) => res.json(diagnostics.clear()));
+  router.use((error, _req, res, _next) => {
+    if (error && error.type === 'entity.too.large') return res.status(413).json({ error: 'body troppo grande' });
+    if (error instanceof SyntaxError) return res.status(400).json({ error: 'JSON non valido' });
+    return res.status(400).json({ error: String(error.message || error) });
+  });
+  return router;
+}
+module.exports = { diagnosticsRoutes };

package/lib/diagnostics/store.js ADDED Viewed

@@ -0,0 +1,139 @@
+'use strict';
+const DEFAULT_MAX_RECORDS = 500;
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const DEFAULT_MAX_ENTRY_BYTES = 4096;
+const ALLOWED_DURATIONS = new Set([300, 900, 1800, 3600]);
+const LEVELS = new Set(['debug', 'info', 'warn', 'error']);
+const META_KEYS = new Set([
+  'port', 'platform', 'reason', 'durationSeconds', 'count', 'errno', 'client',
+  'cell', 'engine', 'action', 'state', 'transport', 'phase', 'version', 'status', 'node', 'code',
+]);
+const DENIED_KEY = /(authorization|cookie|token|secret|credential|password|prompt|terminal|argv|command|env|content|payload|file|path|endpoint|url)/i;
+function redactText(value, max = 160) {
+  let text = String(value == null ? '' : value).normalize('NFC');
+  text = text.replace(/[\p{Cc}\p{Cf}]/gu, ' ').replace(/\s+/g, ' ').trim();
+  text = text
+    .replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]')
+    .replace(/\b(?:sk|xox[baprs]|gh[pousr]|npm)_[A-Za-z0-9_-]{8,}\b/g, '[redacted]')
+    .replace(/\b(?:token|password|secret|api[_-]?key)\s*[=:]\s*\S+/gi, '[redacted]')
+    .replace(/(?:\/home\/[^/\s]+|\/data\/(?:data|user\/\d+)\/[^/\s]+)(?:\/[^\s]*)?/g, '[path]')
+    .replace(/\b[A-Z][A-Z0-9_]{2,}\s*=\s*\S+/g, '[env]');
+  return text.slice(0, max);
+}
+function sanitizeMeta(meta) {
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return {};
+  const out = {};
+  for (const [key, value] of Object.entries(meta)) {
+    if (!META_KEYS.has(key) || DENIED_KEY.test(key)) continue;
+    if (typeof value === 'boolean') out[key] = value;
+    else if (typeof value === 'number' && Number.isFinite(value)) out[key] = value;
+    else if (typeof value === 'string') out[key] = redactText(value, 96);
+  }
+  return out;
+}
+function createDiagnostics(opts = {}) {
+  const now = typeof opts.now === 'function' ? opts.now : Date.now;
+  const maxRecords = opts.maxRecords || DEFAULT_MAX_RECORDS;
+  const maxBytes = opts.maxBytes || DEFAULT_MAX_BYTES;
+  const maxEntryBytes = opts.maxEntryBytes || DEFAULT_MAX_ENTRY_BYTES;
+  let entries = [];
+  let bytes = 0;
+  let seq = 0;
+  let enabledUntil = 0;
+  let expiryRecorded = false;
+  function push(level, component, code, message, meta = {}) {
+    const record = {
+      seq: ++seq,
+      ts: new Date(now()).toISOString(),
+      level,
+      component: redactText(component, 48) || 'runtime',
+      code: /^[A-Z][A-Z0-9_]{0,63}$/.test(String(code || '')) ? String(code) : 'DIAGNOSTIC_EVENT',
+      message: redactText(message, 240) || 'Diagnostic event',
+      meta: sanitizeMeta(meta),
+    };
+    let size = Buffer.byteLength(JSON.stringify(record));
+    if (size > maxEntryBytes) {
+      record.meta = {};
+      record.message = record.message.slice(0, 96);
+      size = Buffer.byteLength(JSON.stringify(record));
+    }
+    if (size > maxEntryBytes) return null;
+    entries.push({ record, size }); bytes += size;
+    while (entries.length > maxRecords || bytes > maxBytes) {
+      const removed = entries.shift(); bytes -= removed.size;
+    }
+    return record;
+  }
+  function refreshExpiry() {
+    if (enabledUntil > 0 && now() >= enabledUntil) {
+      enabledUntil = 0;
+      if (!expiryRecorded) {
+        expiryRecorded = true;
+        push('info', 'diagnostics', 'VERBOSE_EXPIRED', 'Verbose diagnostics expired', { reason: 'timeout' });
+      }
+    }
+  }
+  function record(level, component, code, message, meta = {}) {
+    if (!LEVELS.has(level)) return null;
+    refreshExpiry();
+    if ((level === 'debug' || level === 'info') && enabledUntil === 0) return null;
+    return push(level, component, code, message, meta);
+  }
+  function setVerbose(enabled, durationSeconds = 900) {
+    if (typeof enabled !== 'boolean') throw new Error('enabled deve essere boolean');
+    if (enabled) {
+      if (!ALLOWED_DURATIONS.has(durationSeconds)) throw new Error('durationSeconds deve essere 300, 900, 1800 o 3600');
+      enabledUntil = now() + durationSeconds * 1000;
+      expiryRecorded = false;
+      push('info', 'diagnostics', 'VERBOSE_ENABLED', 'Verbose diagnostics enabled', { durationSeconds });
+    } else {
+      enabledUntil = 0;
+      expiryRecorded = true;
+      push('info', 'diagnostics', 'VERBOSE_DISABLED', 'Verbose diagnostics disabled', { reason: 'manual' });
+    }
+    return status();
+  }
+  function clear() {
+    refreshExpiry();
+    const count = entries.length;
+    entries = []; bytes = 0;
+    push('info', 'diagnostics', 'LOGS_CLEARED', 'Diagnostic buffer cleared', { count });
+    return { cleared: count, ...status() };
+  }
+  function status() {
+    refreshExpiry();
+    return {
+      verbose: enabledUntil > 0,
+      expiresAt: enabledUntil > 0 ? new Date(enabledUntil).toISOString() : null,
+      nextSeq: seq + 1,
+      retained: entries.length,
+      bytes,
+      limits: { records: maxRecords, bytes: maxBytes, entryBytes: maxEntryBytes },
+    };
+  }
+  function logs({ after = 0, limit = 200 } = {}) {
+    refreshExpiry();
+    if (!Number.isSafeInteger(after) || after < 0) throw new Error('after non valido');
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200) throw new Error('limit non valido (1..200)');
+    const records = entries.map((item) => item.record).filter((entry) => entry.seq > after).slice(0, limit);
+    return { records, cursor: records.length ? records[records.length - 1].seq : after, ...status() };
+  }
+  return { record, setVerbose, clear, status, logs };
+}
+module.exports = {
+  DEFAULT_MAX_RECORDS, DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRY_BYTES,
+  ALLOWED_DURATIONS, redactText, sanitizeMeta, createDiagnostics,
+};