@mmmbuto/nexuscrew 0.8.44 → 0.8.45

package/lib/cli/pidfile.js

@@ -18,11 +18,40 @@ function readPidfile(p) {
   } catch (_) { return null; }
 }
 
+function currentUid() {
+  try { return typeof process.getuid === 'function' ? process.getuid() : null; }
+  catch (_) { return null; }
+}
+
+// `/proc/<pid>/stat` field 22 is the kernel start tick.  Unlike a PID or an
+// argv it cannot be recreated by a later process.  macOS has no /proc, so a
+// conservative `ps lstart` fallback still combines with UID, argv and runId.
+function readProcessStart(pid) {
+  try {
+    const raw = fs.readFileSync(`/proc/${pid}/stat`, 'utf8').trim();
+    const match = raw.match(/^\d+\s+\([^)]*\)\s+(.+)$/);
+    const fields = match && match[1].trim().split(/\s+/);
+    const ticks = fields && fields[19]; // field 22, after state=field 3
+    if (/^\d+$/.test(String(ticks || ''))) return `linux:${ticks}`;
+  } catch (_) {}
+  try {
+    const text = execFileSync('ps', ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8' }).trim();
+    return text ? `ps:${text}` : null;
+  } catch (_) { return null; }
+}
+
 // Exclusive create (wx): fallisce se il pidfile esiste già (no overwrite silenzioso).
 function writePidfile(p, pid, cmd, extra = {}) {
   fs.mkdirSync(path.dirname(p), { recursive: true });
   const safeExtra = extra && typeof extra === 'object' && !Array.isArray(extra) ? extra : {};
-  const meta = JSON.stringify({ pid, cmd: cmd || '', startTs: Date.now(), ...safeExtra });
+  const processStart = readProcessStart(pid);
+  const uid = currentUid();
+  const meta = JSON.stringify({
+    pid, cmd: cmd || '', startTs: Date.now(),
+    ...(uid === null ? {} : { uid }),
+    ...(processStart ? { processStart } : {}),
+    ...safeExtra,
+  });
   fs.writeFileSync(p, meta + '\n', { flag: 'wx', mode: 0o600 });
 }
 
@@ -78,6 +107,19 @@ function isAlive(meta, impl = {}) {
   return true;
 }
 
+// Strong ownership used by per-slot reverse supervisors.  Older generic
+// pidfiles remain readable for lifecycle compatibility, but a rotatable slot
+// is never stopped or adopted unless all four local facts are present.
+function isAttributable(meta, impl = {}) {
+  if (!meta || !Number.isFinite(meta.pid) || !Number.isInteger(meta.uid)
+    || typeof meta.processStart !== 'string' || !meta.processStart) return false;
+  const uid = impl.currentUidImpl ? impl.currentUidImpl() : currentUid();
+  if (uid === null || uid !== meta.uid) return false;
+  if (!isAlive(meta, impl)) return false;
+  const liveStart = (impl.readProcessStartImpl || readProcessStart)(meta.pid);
+  return typeof liveStart === 'string' && liveStart === meta.processStart;
+}
+
 // Rimuove pidfile stale (pid morto o non verificabile). Ritorna true se rimosso.
 function cleanStale(p, impl = {}) {
   const meta = readPidfile(p);
@@ -122,5 +164,6 @@ function killPidfile(p, signal = 'SIGTERM', impl = {}) {
 
 module.exports = {
   defaultPidfilePath, readPidfile, writePidfile, removePidfile,
-  pidOwnership, pidExists, readCmdline, isAlive, cleanStale, killPidfile,
+  currentUid, readProcessStart, pidOwnership, pidExists, readCmdline,
+  isAlive, isAttributable, cleanStale, killPidfile,
 };

package/lib/fleet/builtin.js

@@ -296,7 +296,7 @@ async function createBuiltinFleet(cfg = {}) {
     cfg, home, defsPath, tmuxBin, readonly, launchBroker, boot, ensureProtection,
   });
   const {
-    status, up, down, restart, isCellSession,
+    status, cellStatus, up, down, restart, isCellSession,
     reloadDefs, findCell, findEngine, refreshSessions, commitDefs,
   } = rt;
 
@@ -861,7 +861,7 @@ async function createBuiltinFleet(cfg = {}) {
   return {
     available: true,
     provider: 'builtin',
-    status, up, down, restart, engine: setEngine, boot: setBoot, isCellSession,
+    status, cellStatus, up, down, restart, engine: setEngine, boot: setBoot, isCellSession,
     defineEngine, editEngine, removeEngine,
     defineCell, editCell, removeCell, importCell, restoreCells, restoreEngines,
     schema, definitions, capabilities,

package/lib/fleet/managed.js

@@ -503,12 +503,24 @@ async function discoverOllamaModels(opts = {}) {
   }
 }
 
+// Una discovery esterna non deve mai consumare l'intero budget del bridge MCP
+// (10 s): il caller ha ancora margine per serializzare la directory e fallire
+// in modo diagnostico. Ogni futura discovery tramite binario deve usare lo
+// stesso contratto bounded + negative-cache, non una retry ad ogni richiesta.
+const EXTERNAL_DISCOVERY_TIMEOUT_MS = 5000;
 let piCache = { at: 0, providers: {} };
 let piInFlight = null;
+function copyPiProviders(providers) {
+  return Object.fromEntries(Object.entries(providers).map(([key, models]) => [key, [...models]]));
+}
+
 async function discoverPiModels(opts = {}) {
   const now = Date.now(); const ttl = opts.ttlMs === undefined ? 300000 : opts.ttlMs;
-  if (!opts.noCache && Object.keys(piCache.providers).length && now - piCache.at < ttl) {
-    return Object.fromEntries(Object.entries(piCache.providers).map(([k, v]) => [k, [...v]]));
+  // `at`, non il contenuto, rende valida anche una failure cacheata: una lista
+  // vuota e' un risultato operativo, non il segnale di rilanciare un binario
+  // eventualmente bloccato ad ogni richiesta.
+  if (!opts.noCache && piCache.at > 0 && now - piCache.at < ttl) {
+    return copyPiProviders(piCache.providers);
   }
   const home = opts.home || require('node:os').homedir();
   const binary = opts.binary || findBinary('pi', home);
@@ -516,24 +528,38 @@ async function discoverPiModels(opts = {}) {
   if (!opts.noCache && piInFlight) return piInFlight;
   const execFileImpl = opts.execFileImpl || execFile;
   const load = async () => {
-    const stdout = await new Promise((resolve, reject) => {
-      execFileImpl(binary, ['--list-models'], { encoding: 'utf8', timeout: 15000, maxBuffer: 1024 * 1024 }, (err, out) => {
-        if (err) reject(err); else resolve(String(out || ''));
+    try {
+      const stdout = await new Promise((resolve, reject) => {
+        execFileImpl(binary, ['--list-models'], {
+          encoding: 'utf8', timeout: opts.timeoutMs === undefined ? EXTERNAL_DISCOVERY_TIMEOUT_MS : opts.timeoutMs,
+          maxBuffer: 1024 * 1024,
+        }, (err, out) => {
+          if (err) reject(err); else resolve(String(out || ''));
+        });
       });
-    });
-    const providers = {};
-    for (const line of stdout.split(/\r?\n/).slice(1)) {
-      const [provider, model] = line.trim().split(/\s+/);
-      if (!PROVIDER_ID_RE.test(provider || '') || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(model || '')) continue;
-      (providers[provider] ||= []).push(model);
+      const providers = {};
+      for (const line of stdout.split(/\r?\n/).slice(1)) {
+        const [provider, model] = line.trim().split(/\s+/);
+        if (!PROVIDER_ID_RE.test(provider || '') || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(model || '')) continue;
+        (providers[provider] ||= []).push(model);
+      }
+      for (const key of Object.keys(providers)) providers[key] = [...new Set(providers[key])];
+      piCache = { at: now, providers };
+      return copyPiProviders(providers);
+    } catch (_) {
+      // Cache negativa: una failure (timeout compreso) vale per il TTL intero.
+      // Questo mantiene le route Fleet disponibili anche quando un binario di
+      // discovery e' installato ma non risponde.
+      // `noCache` e' un refresh diagnostico richiesto dall'operatore: se
+      // fallisce non deve avvelenare una cache condivisa ancora valida.
+      if (!opts.noCache) piCache = { at: now, providers: {} };
+      return {};
     }
-    for (const key of Object.keys(providers)) providers[key] = [...new Set(providers[key])];
-    piCache = { at: now, providers };
-    return Object.fromEntries(Object.entries(providers).map(([k, v]) => [k, [...v]]));
   };
-  if (opts.noCache) {
-    try { return await load(); } catch (_) { return {}; }
-  }
+  if (opts.noCache) return load();
+  // load() assorbe gia' gli errori operativi. Il catch e' una cintura per una
+  // futura regressione: chi aspetta il single-flight non deve mai ricevere un
+  // rejection che renda la directory Fleet indisponibile.
   piInFlight = load().catch(() => ({})).finally(() => { piInFlight = null; });
   return piInFlight;
 }
@@ -893,7 +919,7 @@ module.exports = {
   ALIBABA_CODEX_MODELS, ALIBABA_TOKEN_PLAN_CONTEXT, ALIBABA_PI_MODELS,
   CLIENT_LABELS, normalizeManagedSpec, profileFor,
   defaultDefinitions, defaultShellEngine, defaultAgyEngine, describeManaged, describeCatalogCredential, discoverOllamaModels, resolveManagedEngine, needsExplicitNode,
-  discoverPiModels, parseEnvFile, parseProviderShellFile, findBinary, publicCatalog, writePiProviderExtension,
+  discoverPiModels, EXTERNAL_DISCOVERY_TIMEOUT_MS, parseEnvFile, parseProviderShellFile, findBinary, publicCatalog, writePiProviderExtension,
   providerKeyPaths, parseProviderKeyFiles, credentialSources, credential,
   credentialEnvNeutralizeSet, applyStoreNeutralization,
   ensureKimiClaudeConfig, ensureAlibabaClaudeConfig, resolveInteractiveShell,

package/lib/fleet/runtime.js

@@ -69,7 +69,10 @@ function createBuiltinRuntime(ctx) {
     return set;
   }
 
-  async function status() {
+  // La directory cella e il trasporto MCP dipendono soltanto da definizioni e
+  // tmux. Tenerla separata dai cataloghi modello evita che un binario esterno
+  // lento trasformi `/api/cells` in un falso guasto della flotta.
+  async function cellStatus() {
     if (Date.now() - cache.at > STATUS_TTL_MS) {
       reloadDefs();                          // pick-up di edit esterne/file
       const sessions = await refreshSessions();
@@ -98,10 +101,26 @@ function createBuiltinRuntime(ctx) {
         rc: '', key: '', degraded: false, // supervisor vivo <=> sessione tmux viva
       };
     });
+    return {
+      available: true,
+      provider: 'builtin',
+      bootOwner: 'builtin',
+      reason: cfg.fleetProviderReason || 'fleet.json definitions',
+      cells,
+    };
+  }
+
+  async function status() {
+    const base = await cellStatus();
     const needsOllama = cache.defs.engines.some((e) => e.managed?.provider === 'ollama-cloud');
-    const ollamaModels = needsOllama ? await discoverOllamaModels({ ...cfg, home }) : [];
     const needsPi = cache.defs.engines.some((e) => e.managed?.client === 'pi');
-    const piModels = needsPi ? await discoverPiModels({ ...cfg, home }) : {};
+    // Le discovery esterne hanno budget propri. Avviarle in parallelo mantiene
+    // il budget dello status sotto quello del bridge invece di sommare i timeout
+    // di Ollama e Pi in sequenza.
+    const [ollamaModels, piModels] = await Promise.all([
+      needsOllama ? discoverOllamaModels({ ...cfg, home }) : [],
+      needsPi ? discoverPiModels({ ...cfg, home }) : {},
+    ]);
     const engines = cache.defs.engines.map((e) => {
       const managed = e.managed ? describeManaged(e.managed, { ...cfg, home }) : null;
       return {
@@ -121,13 +140,7 @@ function createBuiltinRuntime(ctx) {
         } : { kind: 'custom', configured: true, model: e.model?.value || '', models: [] }),
       };
     });
-    return {
-      available: true,
-      provider: 'builtin',
-      bootOwner: 'builtin', // §9b: la UI non puo' mentire su chi possiede il boot
-      reason: cfg.fleetProviderReason || 'fleet.json definitions',
-      cells, engines,
-    };
+    return { ...base, engines };
   }
 
   function isCellSession(name) {
@@ -424,7 +437,7 @@ function createBuiltinRuntime(ctx) {
   }
 
   return {
-    status, up, down, restart, isCellSession,
+    status, cellStatus, up, down, restart, isCellSession,
     reloadDefs, findCell, findEngine, refreshSessions, commitDefs,
   };
 }

package/lib/mcp/cells.js

@@ -121,6 +121,30 @@ function normalizeCellPayload(payload, owner, callerSession = null) {
   return out;
 }
 
+function unavailableOwner(owner, error) {
+  let current = error;
+  for (let depth = 0; current && depth < 4; depth += 1, current = current.cause) {
+    if (current.code === 'NEXUSCREW_HTTP_TIMEOUT') {
+      return {
+        instanceId: owner.instanceId,
+        owner: owner.label,
+        route: owner.route.length ? owner.route.join('/') : 'local',
+        ...(owner.route.length === 0 ? { local: true } : {}),
+        failure: 'timeout',
+      };
+    }
+  }
+  const message = String(error && error.message || error || '');
+  const name = String(error && error.name || '');
+  return {
+    instanceId: owner.instanceId,
+    owner: owner.label,
+    route: owner.route.length ? owner.route.join('/') : 'local',
+    ...(owner.route.length === 0 ? { local: true } : {}),
+    failure: /timeout/i.test(name) || /\btimeout\b/i.test(message) ? 'timeout' : 'unreachable',
+  };
+}
+
 async function readCellDirectory(ctx, callerSession = null) {
   const [config, topology] = await Promise.all([
     ctx.api('GET', '/api/config'), ctx.api('GET', '/api/topology'),
@@ -136,9 +160,8 @@ async function readCellDirectory(ctx, callerSession = null) {
     if (!apiPath) return;
     try {
       cells.push(...normalizeCellPayload(await ctx.api('GET', apiPath), owner, callerSession));
-    } catch (_) {
-      unavailable.push({ instanceId: owner.instanceId, owner: owner.label,
-        route: owner.route.length ? owner.route.join('/') : 'local' });
+    } catch (error) {
+      unavailable.push(unavailableOwner(owner, error));
     }
   }));
   cells.sort((a, b) => (a.route === 'local' ? -1 : b.route === 'local' ? 1
@@ -150,5 +173,5 @@ async function readCellDirectory(ctx, callerSession = null) {
 module.exports = {
   NODE_PART_RE, NODE_ID_RE, CELL_ID_RE,
   orderedDeckMembers, fleetStatusPath, fleetCellsBySession, routePath,
-  topologyOwners, memberOwnerId, parseCellTarget, normalizeCellPayload, readCellDirectory,
+  topologyOwners, memberOwnerId, parseCellTarget, normalizeCellPayload, unavailableOwner, readCellDirectory,
 };

package/lib/mcp/server.js

@@ -34,6 +34,20 @@ const cells = require('./cells.js');
 // Versione protocollo di fallback se il client non ne dichiara una valida.
 const PROTOCOL_FALLBACK = '2025-03-26';
 const HTTP_TIMEOUT_MS = 10000;
+const HTTP_TIMEOUT_CODE = 'NEXUSCREW_HTTP_TIMEOUT';
+const HTTP_UNREACHABLE_CODE = 'NEXUSCREW_HTTP_UNREACHABLE';
+
+// Trasporta la causa in forma strutturata tra bridge e directory celle. Il
+// messaggio resta per l'operatore, ma la classificazione non dipende dalla
+// lingua o da una regex sul testo prodotto da un altro modulo.
+function transportError(baseUrl, cause) {
+  const timeout = !!(cause && (cause.name === 'TimeoutError' || cause.code === 'ABORT_ERR' || cause.code === 'ETIMEDOUT'));
+  const error = new Error(`NexusCrew non raggiungibile su ${baseUrl} (${timeout ? 'timeout' : 'server spento?'})`);
+  error.name = 'NexusCrewTransportError';
+  error.code = timeout ? HTTP_TIMEOUT_CODE : HTTP_UNREACHABLE_CODE;
+  error.cause = cause;
+  return error;
+}
 
 // JSON-RPC error codes standard.
 const PARSE_ERROR = -32700;
@@ -199,9 +213,7 @@ function createMcpServer(opts = {}) {
         ...(payload !== undefined ? { body: payload } : {}),
         signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
       });
-    } catch (e) {
-      throw new Error(`NexusCrew non raggiungibile su ${baseUrl} (${e && e.name === 'TimeoutError' ? 'timeout' : 'server spento?'})`);
-    }
+    } catch (e) { throw transportError(baseUrl, e); }
     const j = await r.json().catch(() => ({}));
     if (!r.ok) throw new Error(j.error ? `API ${r.status}: ${j.error}` : `API ${r.status}`);
     return j;
@@ -351,6 +363,7 @@ function startMcp(opts = {}) {
 
 module.exports = {
   createMcpServer, startMcp, resolveSession, resolveIdentity, TOOLS,
+  PROTOCOL_FALLBACK, HTTP_TIMEOUT_MS, HTTP_TIMEOUT_CODE, HTTP_UNREACHABLE_CODE, transportError,
   parseCellTarget: cells.parseCellTarget,
   normalizeCellPayload: cells.normalizeCellPayload,
   readCellDirectory: cells.readCellDirectory,

package/lib/nodes/commands.js

@@ -16,6 +16,7 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const store = require('./store.js');
 const tunnel = require('./tunnel.js');
+const reversePool = require('./reverse-pool.js');
 const topologyCache = require('./topology-cache.js');
 const inventory = require('./inventory.js');
 const federation = require('../proxy/federation.js');
@@ -364,6 +365,22 @@ function nodesRemove(opts) {
     log(`nodes remove: impossibile fermare il tunnel (${e.message}); config preservata`);
     return { code: 1, reason: 'tunnel stop failed' };
   }
+  // Pools allocated to an inbound peer are monotonic even after removal: its
+  // old SSH key can still hold permitlisten grants, so a future peer must never
+  // inherit those ports. Ledger first, anchor second preserves the safe
+  // crash direction (an ahead ledger is reconciled by the allocator).
+  if (node.direction === 'inbound' && node.reversePool) {
+    const ledgerPath = opts.reversePoolLedgerPath || reversePool.defaultLedgerPath(home);
+    const ledger = reversePool.loadLedger(ledgerPath);
+    const checked = ledger && reversePool.validateLedgerAnchor(ledger, st.reversePoolAnchor);
+    if (!checked || !checked.ok) {
+      log('nodes remove: ledger reverse non verificabile; config preservata');
+      return { code: 1, reason: 'reverse pool ledger invalid' };
+    }
+    const retired = reversePool.appendLedger(ledger, { type: 'retired', base: node.reversePool.base });
+    reversePool.atomicWriteLedger(ledgerPath, retired);
+    next = { ...next, reversePoolAnchor: reversePool.ledgerHead(retired) };
+  }
   store.atomicWriteStore(nodesPath, next);
   log(`nodes remove: nodo "${name}" rimosso${stopped ? ' (tunnel attivo fermato)' : ''}`);
   return { code: 0, name, stopped };

package/lib/nodes/health.js

@@ -47,7 +47,7 @@ async function nodeHealth({ node, home, fetchImpl, now = Date.now(), force = fal
 
   let health;
   if (node.direction === 'inbound') {
-    if (node.shared !== true) {
+    if (!node.token && node.shared !== true) {
       health = {
         transport: 'unknown', auth: 'unknown', reachability: 'unknown', status: 'passive',
         detail: 'client privato collegato (Share disattivato)', expected: true, managed: false, at: now,
@@ -61,10 +61,31 @@ async function nodeHealth({ node, home, fetchImpl, now = Date.now(), force = fal
       const probed = await probeHealth({
         port: node.localPort, token: node.token, expectedInstanceId: node.nodeId || null, fetchImpl, now,
       });
+      // Un client privato non dovrebbe avere alcun -R. Se la sua porta inbound
+      // risponde e la federation conferma proprio quel peer, e' un reverse
+      // residuo (per esempio un supervisor pre-upgrade): non lo pubblichiamo e
+      // non lo terminiamo, ma smettiamo di dichiararlo "passive".
+      if (node.shared !== true) {
+        if (probed.transport === 'down') {
+          health = {
+            transport: 'unknown', auth: 'unknown', reachability: 'unknown', status: 'passive',
+            detail: 'client privato offline (nessun reverse atteso)', expected: true, managed: false, at: now,
+          };
+        } else if (probed.status === 'healthy') {
+          health = {
+            ...probed, status: 'degraded', code: 'private-reverse-listener', expected: false, managed: false,
+            detail: 'canale reverse attivo nonostante Share disattivato: verificare e riconnettere il peer prima di riattivare Share',
+          };
+        } else {
+          health = {
+            ...probed, status: 'degraded', code: 'private-inbound-listener', expected: false, managed: false,
+            detail: `porta inbound privata in ascolto ma peer non verificato (${probed.detail || 'health non valida'})`,
+          };
+        }
       // The receiving side does not own an inbound client's lifecycle. A
       // client-only (or legacy unknown-role) peer being offline is expected,
       // not a broken server. Live auth/payload failures remain real failures.
-      if (probed.transport === 'down' && (node.rolesKnown !== true || node.roles?.node !== true)) {
+      } else if (probed.transport === 'down' && (node.rolesKnown !== true || node.roles?.node !== true)) {
         health = {
           ...probed, status: 'passive', expected: true, managed: false,
           detail: node.rolesKnown === true ? 'client peer offline (expected)' : 'inbound peer offline',

package/lib/nodes/reverse-pool.js

@@ -0,0 +1,221 @@
+'use strict';
+// Reverse-port pool and append-only ledger.  The ledger is deliberately
+// separate from nodes.json: a node store is rewritten often, whereas reusing a
+// released SSH permitlisten is unsafe until an operator changes that policy.
+// Its anchor lives in nodes.json (validated by the caller) so a deleted or
+// truncated ledger can never make a retired pool allocatable again.
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REVERSE_PORT_BASE = 44001;
+const REVERSE_POOL_SIZE = 3;
+const REVERSE_POOL_STRIDE = 100;
+const LEDGER_VERSION = 1;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+const EPOCH_RE = /^[a-f0-9]{32,64}$/;
+const ENTRY_TYPES = new Set(['allocated', 'retired', 'quarantined']);
+
+function isPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+
+function reversePoolForBase(base) {
+  if (!isPort(base)) return null;
+  const slots = Array.from({ length: REVERSE_POOL_SIZE }, (_, index) => base + (index * REVERSE_POOL_STRIDE));
+  return slots.every(isPort) ? slots : null;
+}
+
+function validReversePoolBase(base) {
+  return Array.isArray(reversePoolForBase(base));
+}
+
+function defaultLedgerPath(home = os.homedir()) {
+  return path.join(home, '.nexuscrew', 'reverse-pool-ledger.json');
+}
+
+function genesisDigest(epoch) {
+  return crypto.createHash('sha256').update(`nexuscrew-reverse-pool-ledger/v${LEDGER_VERSION}\0${epoch}`).digest('hex');
+}
+
+function digestEntry(entry) {
+  return crypto.createHash('sha256').update(JSON.stringify({
+    seq: entry.seq,
+    type: entry.type,
+    base: entry.base,
+    at: entry.at,
+    prevDigest: entry.prevDigest,
+  })).digest('hex');
+}
+
+function parseEntry(entry, previous, expectedSeq) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null;
+  const keys = Object.keys(entry);
+  if (keys.length !== 6 || keys.some((key) => !['seq', 'type', 'base', 'at', 'prevDigest', 'digest'].includes(key))) return null;
+  if (!Number.isSafeInteger(entry.seq) || entry.seq !== expectedSeq || !ENTRY_TYPES.has(entry.type)
+    || !validReversePoolBase(entry.base) || !Number.isSafeInteger(entry.at) || entry.at < 0
+    || !DIGEST_RE.test(String(entry.prevDigest || '')) || !DIGEST_RE.test(String(entry.digest || ''))
+    || entry.prevDigest !== previous || digestEntry(entry) !== entry.digest) return null;
+  return { seq: entry.seq, type: entry.type, base: entry.base, at: entry.at, prevDigest: entry.prevDigest, digest: entry.digest };
+}
+
+function parseLedger(raw) {
+  try {
+    const source = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!source || typeof source !== 'object' || Array.isArray(source)) return null;
+    const keys = Object.keys(source);
+    if (keys.length !== 3 || keys.some((key) => !['version', 'epoch', 'entries'].includes(key))) return null;
+    if (source.version !== LEDGER_VERSION || !EPOCH_RE.test(String(source.epoch || ''))
+      || !Array.isArray(source.entries) || source.entries.length > 65535) return null;
+    let previous = genesisDigest(source.epoch);
+    const entries = [];
+    for (let index = 0; index < source.entries.length; index += 1) {
+      const entry = parseEntry(source.entries[index], previous, index + 1);
+      if (!entry) return null;
+      previous = entry.digest;
+      entries.push(entry);
+    }
+    return { version: LEDGER_VERSION, epoch: source.epoch, entries };
+  } catch (_) { return null; }
+}
+
+function emptyLedger(epoch = crypto.randomBytes(16).toString('hex')) {
+  if (!EPOCH_RE.test(epoch)) throw new Error('ledger epoch non valido');
+  return { version: LEDGER_VERSION, epoch, entries: [] };
+}
+
+function ledgerHead(ledger) {
+  const parsed = parseLedger(ledger);
+  if (!parsed) return null;
+  const last = parsed.entries.at(-1);
+  return {
+    epoch: parsed.epoch,
+    seq: last ? last.seq : 0,
+    digest: last ? last.digest : genesisDigest(parsed.epoch),
+  };
+}
+
+function appendLedger(ledger, { type, base, at = Date.now() } = {}) {
+  const parsed = parseLedger(ledger);
+  if (!parsed) throw new Error('reverse pool ledger non valido');
+  if (!ENTRY_TYPES.has(type) || !validReversePoolBase(base) || !Number.isSafeInteger(at) || at < 0) {
+    throw new Error('entry reverse pool ledger non valida');
+  }
+  const head = ledgerHead(parsed);
+  const entry = { seq: head.seq + 1, type, base, at, prevDigest: head.digest };
+  entry.digest = digestEntry(entry);
+  return { ...parsed, entries: [...parsed.entries, entry] };
+}
+
+function parseAnchor(anchor) {
+  if (!anchor || typeof anchor !== 'object' || Array.isArray(anchor)) return null;
+  if (Object.keys(anchor).length !== 3 || !EPOCH_RE.test(String(anchor.epoch || ''))
+    || !Number.isSafeInteger(anchor.seq) || anchor.seq < 0 || !DIGEST_RE.test(String(anchor.digest || ''))) return null;
+  return { epoch: anchor.epoch, seq: anchor.seq, digest: anchor.digest };
+}
+
+// A ledger can legitimately be ahead of the anchor after an interruption
+// between its atomic write and nodes.json's atomic anchor update.  That is
+// conservative and is reconciled by returning advanceAnchor.  Any missing
+// prefix is unsafe and blocks only fresh pool allocation; existing tunnels are
+// intentionally not affected.
+function validateLedgerAnchor(ledger, anchor) {
+  const parsed = parseLedger(ledger);
+  const expected = parseAnchor(anchor);
+  if (!parsed) return { ok: false, code: 'reverse-pool-ledger-invalid', allocationBlocked: true };
+  if (!expected) return { ok: false, code: 'reverse-pool-anchor-missing', allocationBlocked: true };
+  if (parsed.epoch !== expected.epoch) return { ok: false, code: 'reverse-pool-anchor-epoch-mismatch', allocationBlocked: true };
+  const head = ledgerHead(parsed);
+  if (head.seq < expected.seq) return { ok: false, code: 'reverse-pool-ledger-behind-anchor', allocationBlocked: true };
+  const prefix = expected.seq === 0
+    ? { epoch: parsed.epoch, seq: 0, digest: genesisDigest(parsed.epoch) }
+    : parsed.entries[expected.seq - 1];
+  if (!prefix || prefix.digest !== expected.digest) return { ok: false, code: 'reverse-pool-anchor-prefix-mismatch', allocationBlocked: true };
+  if (head.seq > expected.seq) return { ok: true, code: 'reverse-pool-anchor-advance', allocationBlocked: false, advanceAnchor: head };
+  return { ok: true, code: 'reverse-pool-anchor-current', allocationBlocked: false, anchor: head };
+}
+
+function loadLedger(ledgerPath) {
+  try {
+    const st = fs.lstatSync(ledgerPath);
+    if (!st.isFile() || st.isSymbolicLink()) return null;
+    return parseLedger(fs.readFileSync(ledgerPath, 'utf8'));
+  } catch (_) { return null; }
+}
+
+function atomicWriteLedger(ledgerPath, ledger) {
+  const parsed = parseLedger(ledger);
+  if (!parsed) throw new Error('reverse pool ledger non valido');
+  try {
+    if (fs.lstatSync(ledgerPath).isSymbolicLink()) throw new Error('reverse pool ledger target e\' un symlink');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const dir = path.dirname(ledgerPath);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(dir, `.${path.basename(ledgerPath)}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, ledgerPath);
+  } catch (error) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw error;
+  }
+  return parsed;
+}
+
+function usedPorts(nodes = [], ledger = null) {
+  const ports = new Set();
+  for (const node of nodes || []) {
+    if (isPort(node && node.localPort)) ports.add(node.localPort);
+    if (isPort(node && node.reversePort)) ports.add(node.reversePort);
+    const pool = node && node.reversePool;
+    if (pool && validReversePoolBase(pool.base)) for (const port of reversePoolForBase(pool.base)) ports.add(port);
+  }
+  const parsed = parseLedger(ledger);
+  for (const entry of (parsed && parsed.entries) || []) {
+    // An allocation is permanent for this ledger's epoch.  Keeping every
+    // allocated base reserved is what prevents a removed peer's old SSH key
+    // from binding a newly assigned pool.
+    if (entry.type === 'allocated' && validReversePoolBase(entry.base)) {
+      for (const port of reversePoolForBase(entry.base)) ports.add(port);
+    }
+  }
+  return ports;
+}
+
+function nextReversePool(nodes = [], ledger = null, { start = REVERSE_PORT_BASE } = {}) {
+  const occupied = usedPorts(nodes, ledger);
+  for (let base = start; validReversePoolBase(base); base += 1) {
+    const slots = reversePoolForBase(base);
+    if (slots.every((port) => !occupied.has(port))) return { base, slots };
+  }
+  throw new Error('nessun reverse port pool disponibile');
+}
+
+async function allocateAvailableReversePool(nodes = [], ledger = null, {
+  start = REVERSE_PORT_BASE,
+  canBind = async () => true,
+} = {}) {
+  const occupied = usedPorts(nodes, ledger);
+  for (let base = start; validReversePoolBase(base); base += 1) {
+    const slots = reversePoolForBase(base);
+    if (!slots.every((port) => !occupied.has(port))) continue;
+    let available = true;
+    for (const port of slots) {
+      if (!(await canBind(port))) { available = false; break; }
+    }
+    if (available) return { base, slots };
+  }
+  throw new Error('nessun reverse port pool disponibile');
+}
+
+module.exports = {
+  REVERSE_PORT_BASE, REVERSE_POOL_SIZE, REVERSE_POOL_STRIDE, LEDGER_VERSION,
+  reversePoolForBase, validReversePoolBase, defaultLedgerPath,
+  genesisDigest, digestEntry, parseLedger, emptyLedger, ledgerHead, appendLedger,
+  parseAnchor, validateLedgerAnchor, loadLedger, atomicWriteLedger,
+  usedPorts, nextReversePool, allocateAvailableReversePool,
+};