@mmmbuto/nexuscrew 0.8.44 → 0.8.46

package/lib/nodes/store.js

@@ -17,8 +17,10 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const reversePool = require('./reverse-pool.js');
 
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 3;
+const PREVIOUS_SCHEMA_VERSION = 2;
 const LEGACY_SCHEMA_VERSION = 1;
 const MAX_NODES = 64;
 const MAX_TOKEN_LEN = 4096;
@@ -105,8 +107,89 @@ const LABEL_MAX = 64;
 const NODE_KEYS = new Set([
   'name', 'ssh', 'sshPort', 'remotePort', 'localPort', 'keyPath', 'identityFile',
   'roles', 'rolesKnown', 'token', 'acceptToken', 'nodeId', 'transport', 'autostart', 'visibility', 'selected',
-  'direction', 'reversePort', 'shared', 'label',
+  'direction', 'reversePort', 'shared', 'label', 'reversePool',
 ]);
+
+const REVERSE_POOL_SLOT_STATES = new Set(['active', 'ready', 'reserved', 'draining', 'quarantined', 'retired']);
+const REVERSE_POOL_VERIFICATIONS = new Set(['verified', 'unverifiable', 'missing', 'invalidated']);
+const REVERSE_POOL_PHASES = new Set(['active', 'prepared', 'switched', 'abandoned']);
+
+function parseReversePool(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const keys = Object.keys(value);
+  if (keys.some((key) => !['base', 'slots', 'activeSlot', 'activeGeneration', 'verification', 'verifiedSlots', 'rotation', 'lastAutoRotationAt'].includes(key))) return null;
+  const ports = reversePool.reversePoolForBase(value.base);
+  if (!ports || !Array.isArray(value.slots) || value.slots.length !== ports.length
+    || !Number.isInteger(value.activeSlot) || value.activeSlot < 0 || value.activeSlot >= ports.length
+    || !Number.isSafeInteger(value.activeGeneration) || value.activeGeneration < 1
+    || !REVERSE_POOL_VERIFICATIONS.has(value.verification)) return null;
+  if (value.lastAutoRotationAt !== undefined && (!Number.isSafeInteger(value.lastAutoRotationAt) || value.lastAutoRotationAt < 0)) return null;
+  const verifiedSlots = value.verifiedSlots === undefined ? [] : value.verifiedSlots;
+  if (!Array.isArray(verifiedSlots) || verifiedSlots.length > ports.length
+    || new Set(verifiedSlots).size !== verifiedSlots.length
+    || verifiedSlots.some((slot) => !Number.isInteger(slot) || slot < 0 || slot >= ports.length)) return null;
+  if (value.verification === 'verified' && verifiedSlots.length !== ports.length) return null;
+  const slots = value.slots.map((slot, index) => {
+    if (!slot || typeof slot !== 'object' || Array.isArray(slot) || Object.keys(slot).some((key) => !['port', 'state', 'generation'].includes(key))) return null;
+    if (slot.port !== ports[index] || !REVERSE_POOL_SLOT_STATES.has(slot.state)
+      || !Number.isSafeInteger(slot.generation) || slot.generation < 1) return null;
+    return { port: slot.port, state: slot.state, generation: slot.generation };
+  });
+  if (slots.some((slot) => !slot) || slots[value.activeSlot].state !== 'active'
+    || slots[value.activeSlot].generation !== value.activeGeneration) return null;
+  let rotation = { phase: 'active', generation: value.activeGeneration, slot: value.activeSlot };
+  if (value.rotation !== undefined) {
+    const r = value.rotation;
+    if (!r || typeof r !== 'object' || Array.isArray(r)
+      || Object.keys(r).some((key) => !['phase', 'generation', 'slot', 'leaseId', 'expiresAt', 'oldSlot', 'oldGeneration', 'graceUntil'].includes(key))
+      || !REVERSE_POOL_PHASES.has(r.phase) || !Number.isSafeInteger(r.generation) || r.generation < 1
+      || !Number.isInteger(r.slot) || r.slot < 0 || r.slot >= ports.length) return null;
+    if (r.phase === 'prepared') {
+      if (typeof r.leaseId !== 'string' || !/^[a-f0-9]{32,64}$/.test(r.leaseId)
+        || !Number.isSafeInteger(r.expiresAt) || r.expiresAt < 0) return null;
+    } else if (r.phase === 'switched') {
+      if (!Number.isInteger(r.oldSlot) || r.oldSlot < 0 || r.oldSlot >= ports.length || r.oldSlot === r.slot
+        || !Number.isSafeInteger(r.oldGeneration) || r.oldGeneration < 1
+        || !Number.isSafeInteger(r.graceUntil) || r.graceUntil < 0
+        || r.leaseId !== undefined || r.expiresAt !== undefined) return null;
+    } else if (r.leaseId !== undefined || r.expiresAt !== undefined || r.oldSlot !== undefined
+      || r.oldGeneration !== undefined || r.graceUntil !== undefined) return null;
+    rotation = { phase: r.phase, generation: r.generation, slot: r.slot,
+      ...(r.phase === 'prepared' ? { leaseId: r.leaseId, expiresAt: r.expiresAt } : {}),
+      ...(r.phase === 'switched' ? { oldSlot: r.oldSlot, oldGeneration: r.oldGeneration, graceUntil: r.graceUntil } : {}) };
+  }
+  return {
+    base: value.base,
+    slots,
+    activeSlot: value.activeSlot,
+    activeGeneration: value.activeGeneration,
+    verification: value.verification,
+    verifiedSlots: [...verifiedSlots].sort((a, b) => a - b),
+    rotation,
+    ...(value.lastAutoRotationAt === undefined ? {} : { lastAutoRotationAt: value.lastAutoRotationAt }),
+  };
+}
+
+function parseReversePoolAnchor(value) {
+  return reversePool.parseAnchor(value);
+}
+
+function reversePoolDefault(base, { verification = 'unverifiable', generation = 1 } = {}) {
+  const ports = reversePool.reversePoolForBase(base);
+  if (!ports || !REVERSE_POOL_VERIFICATIONS.has(verification) || !Number.isSafeInteger(generation) || generation < 1) {
+    throw new Error('reverse pool non valida');
+  }
+  return {
+    base,
+    slots: ports.map((port, index) => ({ port, state: index === 0 ? 'active' : 'ready', generation })),
+    activeSlot: 0,
+    activeGeneration: generation,
+    verification,
+    verifiedSlots: verification === 'verified' ? ports.map((_, index) => index) : [],
+    rotation: { phase: 'active', generation, slot: 0 },
+  };
+}
+
 function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   if (!n || typeof n !== 'object' || Array.isArray(n)) return null;
   for (const k of Object.keys(n)) { if (!NODE_KEYS.has(k)) return null; } // schema chiuso
@@ -170,6 +253,12 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     if (!isPort(n.reversePort)) return null;
     out.reversePort = n.reversePort;
   }
+  if (n.reversePool !== undefined) {
+    if (schemaVersion < SCHEMA_VERSION) return null;
+    const parsedPool = parseReversePool(n.reversePool);
+    if (!parsedPool) return null;
+    out.reversePool = parsedPool;
+  }
   if (n.selected !== undefined) {
     if (!Array.isArray(n.selected) || n.selected.length > MAX_NODES) return null;
     const selected = [...new Set(n.selected)];
@@ -222,7 +311,11 @@ function parseStore(raw) {
       return null;
     }
 
-    if (d.schemaVersion !== SCHEMA_VERSION && d.schemaVersion !== LEGACY_SCHEMA_VERSION) return null;
+    if (![SCHEMA_VERSION, PREVIOUS_SCHEMA_VERSION, LEGACY_SCHEMA_VERSION].includes(d.schemaVersion)) return null;
+    const rootKeys = d.schemaVersion === SCHEMA_VERSION
+      ? new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous', 'reversePoolAnchor', 'reversePoolLedgerInitialized'])
+      : new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous']);
+    if (Object.keys(d).some((key) => !rootKeys.has(key))) return null;
     if (typeof d.nodeId !== 'string' || !NODE_ID_RE.test(d.nodeId)) return null;
     if (!Array.isArray(d.nodes) || d.nodes.length > MAX_NODES) return null;
 
@@ -252,6 +345,24 @@ function parseStore(raw) {
       if (!rdv) return null;
       out.rendezvous = rdv;
     }
+    if (d.schemaVersion === SCHEMA_VERSION) {
+      // This marker distinguishes a fresh v3 peer (which may have received a
+      // pool from another hub) from a hub that has once owned allocations. If
+      // the latter loses its anchor, it must not silently start a new ledger.
+      if (d.reversePoolLedgerInitialized !== undefined && d.reversePoolLedgerInitialized !== true) return null;
+      if (d.reversePoolLedgerInitialized === true) out.reversePoolLedgerInitialized = true;
+      if (d.reversePoolAnchor !== undefined) {
+        if (d.reversePoolLedgerInitialized !== true) return null;
+        const anchor = parseReversePoolAnchor(d.reversePoolAnchor);
+        if (!anchor) return null;
+        out.reversePoolAnchor = anchor;
+      }
+      // The allocator and monotonic ledger live on the hub, which owns inbound
+      // peers.  An outbound peer persists the pool negotiated by that hub but
+      // must not invent a second local allocation ledger for it.
+      if (nodes.some((node) => node.direction === 'inbound' && node.reversePool)
+        && (!out.reversePoolAnchor || d.reversePoolLedgerInitialized !== true)) return null;
+    }
     return out;
   } catch (_) {
     return null; // fail-closed: qualunque eccezione inattesa -> null, MAI throw
@@ -366,8 +477,12 @@ function getNode(store, name) {
   return store.nodes.find((n) => n.name === name) || null;
 }
 
+function mutationSchemaVersion(store) {
+  return store && store.schemaVersion === SCHEMA_VERSION ? SCHEMA_VERSION : PREVIOUS_SCHEMA_VERSION;
+}
+
 function addNode(store, entry) {
-  const node = parseNode(entry, SCHEMA_VERSION);
+  const node = parseNode(entry, mutationSchemaVersion(store));
   if (!node) throw new Error('nodo non valido (schema strict): controlla name/ssh/remotePort/localPort');
   if (store.nodes.some((n) => n.name === node.name)) {
     throw new Error(`nodo duplicato: name "${node.name}" gia' presente`);
@@ -381,7 +496,7 @@ function addNode(store, entry) {
       throw new Error(`nodo duplicato: nodeId "${node.nodeId}" gia' presente`);
     }
   }
-  return { ...store, schemaVersion: SCHEMA_VERSION, nodes: store.nodes.concat([node]) };
+  return { ...store, schemaVersion: mutationSchemaVersion(store), nodes: store.nodes.concat([node]) };
 }
 
 function removeNode(store, name) {
@@ -389,7 +504,7 @@ function removeNode(store, name) {
   if (idx < 0) throw new Error(`nodo sconosciuto: "${name}"`);
   const nodes = store.nodes.slice();
   nodes.splice(idx, 1);
-  return { ...store, schemaVersion: SCHEMA_VERSION, nodes };
+  return { ...store, schemaVersion: mutationSchemaVersion(store), nodes };
 }
 
 function setNodeToken(store, name, token) {
@@ -398,17 +513,47 @@ function setNodeToken(store, name, token) {
   if (!validToken(token)) throw new Error('token non valido (vuoto, multilinea o troppo lungo)');
   const nodes = store.nodes.slice();
   nodes[idx] = { ...nodes[idx], token };
-  return { ...store, schemaVersion: SCHEMA_VERSION, nodes };
+  return { ...store, schemaVersion: mutationSchemaVersion(store), nodes };
 }
 
 function updateNode(store, name, patch) {
   const idx = store.nodes.findIndex((n) => n.name === name);
   if (idx < 0) throw new Error(`nodo sconosciuto: "${name}"`);
-  const parsed = parseNode({ ...store.nodes[idx], ...patch }, SCHEMA_VERSION);
+  const parsed = parseNode({ ...store.nodes[idx], ...patch }, mutationSchemaVersion(store));
   if (!parsed) throw new Error('aggiornamento nodo non valido');
   const nodes = store.nodes.slice();
   nodes[idx] = parsed;
-  return { ...store, schemaVersion: SCHEMA_VERSION, nodes };
+  return { ...store, schemaVersion: mutationSchemaVersion(store), nodes };
+}
+
+// The upgrade is explicit: normal legacy pairing remains schema v2 and keeps
+// working with a previous NexusCrew binary.  Enabling rotation is the only
+// path that writes the v3 anchor and therefore requires both peers to support
+// the capability.
+function upgradeToReversePoolSchema(store, anchor = undefined) {
+  const current = parseStore(store);
+  if (!current) throw new Error('nodes store non valido');
+  const parsedAnchor = anchor === undefined ? null : parseReversePoolAnchor(anchor);
+  if (anchor !== undefined && !parsedAnchor) throw new Error('reverse pool anchor non valida');
+  const next = {
+    ...current,
+    schemaVersion: SCHEMA_VERSION,
+    ...(parsedAnchor ? { reversePoolLedgerInitialized: true, reversePoolAnchor: parsedAnchor } : {}),
+  };
+  const parsed = parseStore(next);
+  if (!parsed) throw new Error('upgrade reverse pool non valido');
+  return parsed;
+}
+
+function setNodeReversePool(store, name, value) {
+  const current = store && getNode(store, name);
+  if (!store || store.schemaVersion !== SCHEMA_VERSION || !current) {
+    throw new Error('reverse pool richiede schema v3');
+  }
+  if (current.direction === 'inbound' && !parseReversePoolAnchor(store.reversePoolAnchor)) {
+    throw new Error('reverse pool inbound richiede anchor valida');
+  }
+  return updateNode(store, name, { reversePool: value });
 }
 
 // --- Redazione (view sicura per status/list: MAI il token) ------------------
@@ -434,6 +579,18 @@ function redactNode(n) {
   if (n.visibility === 'selected') out.selected = [...(n.selected || [])];
   if (n.sshPort !== undefined) out.sshPort = n.sshPort;
   if (n.nodeId) out.nodeId = n.nodeId;
+  if (n.reversePool) {
+    out.reversePool = {
+      base: n.reversePool.base,
+      slots: n.reversePool.slots.map((slot) => ({ ...slot })),
+      activeSlot: n.reversePool.activeSlot,
+      activeGeneration: n.reversePool.activeGeneration,
+      verification: n.reversePool.verification,
+      verifiedSlots: [...n.reversePool.verifiedSlots],
+      rotation: { ...n.reversePool.rotation },
+      ...(n.reversePool.lastAutoRotationAt === undefined ? {} : { lastAutoRotationAt: n.reversePool.lastAutoRotationAt }),
+    };
+  }
   return out;
 }
 
@@ -577,10 +734,11 @@ function suggestNodeName(input, existing = []) {
 module.exports = {
   // parse/validate
   parseStore, parseNode, parseRendezvous, parseRoles, parseSsh, parseSshTarget, isPort, isAbsPath, validToken,
+  parseReversePool, parseReversePoolAnchor, reversePoolDefault,
   // I/O
   defaultNodesPath, loadStore, loadStoreStrict, initStore, atomicWriteStore, loadOrInitStore, emptyStore, newNodeId,
   // mutazioni
-  getNode, addNode, removeNode, setNodeToken, updateNode,
+  getNode, addNode, removeNode, setNodeToken, updateNode, upgradeToReversePoolSchema, setNodeReversePool,
   // redazione
   redactNode, redactStore, hasPairedPeers,
   // migrazione
@@ -588,5 +746,5 @@ module.exports = {
   // label / slug
   nodeLabel, validLabel, sanitizeLabel, toSlug, deriveNodeHandle, suggestNodeName, LABEL_MAX,
   // costanti
-  SCHEMA_VERSION, LEGACY_SCHEMA_VERSION, MAX_NODES, MAX_TOKEN_LEN, NODE_NAME_RE, NODE_ID_RE,
+  SCHEMA_VERSION, PREVIOUS_SCHEMA_VERSION, LEGACY_SCHEMA_VERSION, MAX_NODES, MAX_TOKEN_LEN, NODE_NAME_RE, NODE_ID_RE,
 };

package/lib/nodes/tunnel-supervisor.js

@@ -89,7 +89,14 @@ function clearForwardProbe() {
 function probeForward(expectedChild) {
   if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
   if (!forwardPort) {
-    writeState('transport-probing', { sshPid: child.pid, detail: 'local forward unavailable' });
+    // A reverse-only sidecar has no local -L to probe.  With
+    // ExitOnForwardFailure enabled, surviving the stability window proves that
+    // ssh accepted its -R request; the hub still performs the stronger MAC
+    // ownership probe before it publishes Share.
+    attempt = 0;
+    reverseFailures = 0;
+    logEvent(`reverse forward ready stableMs=${stableMs}`);
+    if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'reverse-forward' })) stop();
     return;
   }
   let settled = false;

package/lib/nodes/tunnel.js

@@ -44,7 +44,7 @@ function assertForwardSpec(node) {
   if (node.keyPath !== undefined && !store.isAbsPath(node.keyPath)) throw new Error('tunnel: keyPath non valido');
   if (node.reversePort !== undefined && !store.isPort(node.reversePort)) throw new Error('tunnel: reversePort non valida');
   if (node.localAppPort !== undefined && !store.isPort(node.localAppPort)) throw new Error('tunnel: localAppPort non valida');
-  if (node.shared === true && node.reversePort !== undefined && !store.isPort(node.localAppPort)) {
+  if (node.shared === true && node.reversePort !== undefined && !node.reversePool && !store.isPort(node.localAppPort)) {
     throw new Error('tunnel: Share richiede localAppPort esplicita');
   }
   if (!store.parseSshTarget(node.ssh)) throw new Error('tunnel: target ssh non valido');
@@ -61,7 +61,7 @@ function buildForwardArgs(node) {
   // The forward channel is the connection to the hub and is always present.
   // The reverse channel publishes this device back through the hub, so it is
   // opt-in only. A negotiated reversePort alone must never imply consent.
-  const reverse = node.shared === true && node.reversePort !== undefined ? [
+  const reverse = node.shared === true && node.reversePort !== undefined && !node.reversePool ? [
     '-R', `127.0.0.1:${node.reversePort}:127.0.0.1:${node.localAppPort}`,
   ] : [];
   return SSH_BASE_OPTS.concat(transport, identity ? ['-i', identity] : [], [
@@ -71,6 +71,24 @@ function buildForwardArgs(node) {
   ]);
 }
 
+// A rotatable peer keeps its private -L on the primary supervisor and owns a
+// reverse-only supervisor per generation.  No ControlMaster and no hidden
+// rendezvous connection: every process has its own pidfile, intent and slot.
+function buildReverseArgs(node, { remotePort, targetPort } = {}) {
+  assertForwardSpec({ ...node, shared: false });
+  if (!store.isPort(remotePort) || !store.isPort(targetPort)) throw new Error('tunnel: reverse slot non valida');
+  if (!node.reversePool || !Array.isArray(node.reversePool.slots)
+    || !node.reversePool.slots.some((slot) => slot && slot.port === remotePort)) {
+    throw new Error('tunnel: reverse slot non appartiene al pool');
+  }
+  const transport = node.sshPort === undefined ? [] : ['-p', String(node.sshPort)];
+  const identity = node.identityFile || node.keyPath;
+  return SSH_BASE_OPTS.concat(transport, identity ? ['-i', identity] : [], [
+    '-R', `127.0.0.1:${remotePort}:127.0.0.1:${targetPort}`,
+    node.ssh,
+  ]);
+}
+
 // Backoff esponenziale + jitter (design §7). Deterministico con rng iniettato.
 //   delay = clamp(base * factor^attempt, 0..cap) * (1 +- jitter*(2*rand-1))
 // rng()=0.5 -> jitter nullo (ritorna il valore base clamperato); test deterministici.
@@ -106,6 +124,17 @@ function tunnelLogPath(home, name) {
 // runtimes never start this second connection; reconciliation can still stop a
 // stale legacy process left by an older install.
 const REVERSE_NAME = '__rendezvous__';
+const REVERSE_SLOT_NAME_RE = /^reverse-([a-z0-9-]{1,32})-(\d{1,5})-(\d{1,10})$/;
+
+function reverseTunnelName(nodeName, remotePort, generation) {
+  if (!store.NODE_NAME_RE.test(String(nodeName || '')) || !store.isPort(remotePort)
+    || !Number.isSafeInteger(generation) || generation < 1) throw new Error('reverse tunnel name non valido');
+  return `reverse-${nodeName}-${remotePort}-${generation}`;
+}
+
+function isTunnelName(name) {
+  return store.NODE_NAME_RE.test(name) || name === REVERSE_NAME || REVERSE_SLOT_NAME_RE.test(name);
+}
 
 // Reconcile detached supervisors against the authoritative node store. A
 // server crash or an older rollback could leave a valid supervisor pidfile
@@ -120,14 +149,14 @@ function tunnelPidNames(home) {
     return fs.readdirSync(dir, { withFileTypes: true })
       .filter((entry) => entry.isFile() && !entry.isSymbolicLink() && entry.name.endsWith('.pid'))
       .map((entry) => entry.name.slice(0, -4))
-      .filter((name) => store.NODE_NAME_RE.test(name) || name === REVERSE_NAME)
+      .filter((name) => isTunnelName(name))
       .sort();
   } catch (_) { return []; }
 }
 
 function reconcileTunnelSupervisors({ home = os.homedir(), configuredNames = [], stopImpl } = {}) {
   const keep = new Set((Array.isArray(configuredNames) ? configuredNames : [])
-    .filter((name) => store.NODE_NAME_RE.test(String(name || ''))));
+    .filter((name) => isTunnelName(String(name || ''))));
   const stopOne = typeof stopImpl === 'function' ? stopImpl : stopTunnel;
   const result = { kept: [], stopped: [], cleaned: [], failed: [] };
   const safeAbsent = new Set([
@@ -265,6 +294,19 @@ function tunnelStatePath(home, name) {
   return path.join(tunnelDir(home), `${name}.state.json`);
 }
 
+// A reverse sidecar is allowed to be terminated only when we can prove it is
+// this exact NexusCrew generation: same UID, argv/start-time identity and the
+// runId recorded by its own state file.  A stale or foreign pidfile is a
+// diagnostic/quarantine condition, never a reason to signal a PID.
+function tunnelSupervisorAttributable(home, name, meta, impl = {}) {
+  if (!meta || typeof meta.runId !== 'string' || !/^[a-f0-9]{32,64}$/.test(meta.runId)) return false;
+  if (!pidf.isAttributable(meta, impl)) return false;
+  try {
+    const state = JSON.parse((impl.readFileSyncImpl || fs.readFileSync)(tunnelStatePath(home, name), 'utf8'));
+    return state && state.supervisorPid === meta.pid && state.runId === meta.runId;
+  } catch (_) { return false; }
+}
+
 // Stato interrogabile del tunnel: { status: 'up'|'down', pid?, since? }.
 function readTunnelState(home, name) {
   const p = tunnelPidPath(home, name);
@@ -283,7 +325,7 @@ function readTunnelState(home, name) {
       };
     } catch (_) { return null; }
   };
-  if (meta && pidf.isAlive(meta)) {
+  if (meta && pidf.isAttributable(meta)) {
     try {
       const state = JSON.parse(fs.readFileSync(tunnelStatePath(home, name), 'utf8'));
       const transport = typeof state.transport === 'string' ? state.transport : undefined;
@@ -373,6 +415,23 @@ function removeStateIfOwned(home, name, meta) {
   return false;
 }
 
+function writeStartingState(home, name, { pid, runId, transport } = {}) {
+  if (!Number.isFinite(pid) || typeof runId !== 'string' || !/^[a-f0-9]{32,64}$/.test(runId)) return false;
+  const statePath = tunnelStatePath(home, name);
+  const tmp = `${statePath}.tmp.${process.pid}.${runId}`;
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify({
+      status: 'starting', supervisorPid: pid, runId, transport: path.basename(String(transport || 'ssh')), updatedAt: Date.now(), attempt: 0,
+    })}\n`, { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, statePath);
+    return true;
+  } catch (_) {
+    try { fs.unlinkSync(tmp); } catch (_error) {}
+    return false;
+  }
+}
+
 function supervisorExited(pid, timeoutMs = 2500, impl = {}) {
   const deadline = Date.now() + timeoutMs;
   const sleeper = new Int32Array(new SharedArrayBuffer(4));
@@ -425,7 +484,7 @@ function startTunnel(opts) {
   const spawnImpl = opts.spawnImpl || spawn;
   const spawnSyncImpl = opts.spawnSyncImpl || spawnSync;
   const sshBin = opts.sshBin || 'ssh';
-  if (!name) throw new Error('startTunnel: name mancante');
+  if (!isTunnelName(name)) throw new Error('startTunnel: name mancante o non valido');
   if (!Array.isArray(args)) throw new Error('startTunnel: args mancanti');
 
   const pidPath = tunnelPidPath(home, name);
@@ -435,12 +494,18 @@ function startTunnel(opts) {
   const cmd = `${process.execPath} ${supervisorArgs.join(' ')}`;
   const existing = pidf.readPidfile(pidPath);
   if (existing && pidf.isAlive(existing)) {
+    const strictSidecar = REVERSE_SLOT_NAME_RE.test(name);
+    if (strictSidecar && !pidf.isAttributable(existing, opts.pidfileImpl || {})) {
+      return { started: false, reason: 'unattributable existing supervisor', pid: existing.pid };
+    }
+    const stateOwned = !strictSidecar || tunnelSupervisorAttributable(home, name, existing, opts.pidfileImpl || {});
     // An update or automatic HTTP-port fallback can change -L/-R while the
     // detached supervisor is still alive.  Keep exact matches idempotent, but
     // replace a supervisor whose saved argv no longer matches the desired one.
     if (!existing.cmd || existing.cmd === cmd) {
       return { started: false, reason: 'already running', pid: existing.pid, transport: sshBin };
     }
+    if (!stateOwned) return { started: false, reason: 'unattributable existing supervisor', pid: existing.pid };
     const oldMeta = existing;
     const stopped = pidf.killPidfile(pidPath);
     if (!stopped.killed) return { started: false, reason: `running spec mismatch: ${stopped.reason || 'stop failed'}`, pid: existing.pid };
@@ -449,7 +514,7 @@ function startTunnel(opts) {
     }
     removeStateIfOwned(home, name, oldMeta);
   }
-  pidf.cleanStale(pidPath);
+  if (!existing || !pidf.isAlive(existing)) pidf.cleanStale(pidPath);
 
   const logPath = tunnelLogPath(home, name);
   const statePath = tunnelStatePath(home, name);
@@ -528,6 +593,12 @@ function startTunnel(opts) {
     closeOwnedFd();
     return { started: false, reason: 'pidfile error', error: String(e && e.message || e) };
   }
+  if (!writeStartingState(home, name, { pid, runId, transport: sshBin })) {
+    try { process.kill(pid, 'SIGTERM'); } catch (_) {}
+    cleanupIfOwned();
+    closeOwnedFd();
+    return { started: false, reason: 'statefile error' };
+  }
   // Safe local breadcrumb: argv, host, key paths and credentials are omitted.
   // The detached supervisor appends lifecycle events to the same 0600 file.
   if (Number.isInteger(logFd)) {
@@ -544,6 +615,10 @@ function stopTunnel(opts) {
   if (!name) throw new Error('stopTunnel: name mancante');
   const pidPath = tunnelPidPath(home, name);
   const meta = pidf.readPidfile(pidPath);
+  if (meta && REVERSE_SLOT_NAME_RE.test(name) && pidf.isAlive(meta)
+    && !tunnelSupervisorAttributable(home, name, meta, opts.pidfileImpl || {})) {
+    return { stopped: false, pid: meta.pid, reason: 'unattributable supervisor' };
+  }
   const r = pidf.killPidfile(pidPath);
   if (r.killed && !(opts.supervisorExitedImpl || supervisorExited)(r.pid, opts.stopWaitMs || 2500)) {
     return { stopped: false, pid: r.pid, reason: `supervisor ${r.pid} did not exit after SIGTERM` };
@@ -572,6 +647,15 @@ function startForward(opts) {
   return startTunnel({ ...opts, sshBin, name: node.name, args });
 }
 
+function startReverseForward(opts) {
+  const node = opts.node;
+  const remotePort = opts.remotePort;
+  const generation = opts.generation;
+  const args = buildReverseArgs(node, { remotePort, targetPort: opts.targetPort });
+  const name = reverseTunnelName(node.name, remotePort, generation);
+  return startTunnel({ ...opts, sshBin: opts.sshBin || 'ssh', name, args });
+}
+
 // Versione client OpenSSH, solo diagnostica. Non inferire mai da questa la
 // policy `permitlisten` del server remoto: quella si prova con il vero -R.
 function readSshVersion(spawnSyncImpl) {
@@ -586,14 +670,15 @@ function readSshVersion(spawnSyncImpl) {
 
 module.exports = {
   SSH_BASE_OPTS,
-  buildForwardArgs, backoffDelay,
+  buildForwardArgs, buildReverseArgs, backoffDelay,
   tunnelDir, tunnelPidPath, tunnelLogPath, tunnelStatePath, readTunnelState,
   prepareTunnelDir, openTunnelLog,
   tunnelPidNames, reconcileTunnelSupervisors,
   classifySshFailure, readTunnelDiagnostic,
   diagnoseTunnel,
-  removeStateIfOwned, supervisorExited,
-  startTunnel, stopTunnel, restartTunnel, startForward,
-  REVERSE_NAME,
+  removeStateIfOwned, writeStartingState, supervisorExited,
+  tunnelSupervisorAttributable,
+  startTunnel, stopTunnel, restartTunnel, startForward, startReverseForward,
+  REVERSE_NAME, REVERSE_SLOT_NAME_RE, reverseTunnelName, isTunnelName,
   readSshVersion, sshBinaryAvailable,
 };