@mmmbuto/nexuscrew 0.8.9 → 0.8.11

package/lib/cli/commands.js

@@ -1,5 +1,5 @@
 'use strict';
-// CLI dispatcher: init / serve / start / stop / status. [M6][R1]
+// Minimal public CLI plus internal service/MCP entry points. [M6][R1]
 // serve = foreground HTTP (+ --pidfile lifecycle su Termux/manuale).
 // start/stop/status = per-platform: linux (systemctl --user), mac (launchctl),
 // termux (nohup serve --pidfile + pidfile verificato; status boot-script vs running).
@@ -8,23 +8,16 @@ const fs = require('node:fs');
 const path = require('node:path');
 const net = require('node:net');
 const { detectPlatform, nodeBin, repoRoot, uid } = require('./platform.js');
-const { installPath: serviceInstallPath } = require('./service.js');
+const { installPath: serviceInstallPath, ensureLinuxTmuxSurvival } = require('./service.js');
 const { fleetInstallPath } = require('./fleet-service.js');
 const pidf = require('./pidfile.js');
 const { runInit } = require('./init.js');
 const { rotateToken } = require('../auth/token.js');
 const urlmod = require('./url.js');
 const { doctor } = require('./doctor.js');
-const nodesCmds = require('../nodes/commands.js');
 const nodesStore = require('../nodes/store.js');
 const nodesTunnel = require('../nodes/tunnel.js');
 
-// Flag CLI che consumano il token successivo (forma "--k v", oltre a "--k=v").
-// Solo flag esclusivi dei subcomandi nodes/node: non collidono con gli altri.
-const VALUE_FLAGS = new Set([
-  'ssh', 'ssh-port', 'remote-port', 'key', 'local-port', 'node-id', 'rendezvous', 'published-port', 'token',
-]);
-
 const HELP = `NexusCrew — PWA for local and remote AI workers.
 
 Usage:
@@ -32,6 +25,9 @@ Usage:
   nexuscrew show     start when needed and open the authenticated PWA
   nexuscrew show token  print the clickable authenticated URL
   nexuscrew boot     enable startup at boot (use: boot off|status)
+  nexuscrew status   show service, port, roles and node status
+  nexuscrew stop     stop the background service
+  nexuscrew restart  restart the background service
   nexuscrew doctor   run local diagnostics
   nexuscrew help     show this help
   nexuscrew version  show the installed version
@@ -153,57 +149,180 @@ function start(opts = {}) {
   throw new Error(`start: platform ${platform} non supportata`);
 }
 
-function stop(opts = {}) {
+function stopManagedTunnels(opts = {}) {
+  const home = opts.home || require('node:os').homedir();
+  const { configDir } = urlmod.resolvePaths(opts);
+  const nodesPath = opts.nodesPath || path.join(configDir, 'nodes.json');
+  const st = nodesStore.loadStore(nodesPath);
+  const stopped = [];
+  for (const node of (st && st.nodes) || []) {
+    if (node.direction === 'inbound') continue;
+    try { nodesTunnel.stopTunnel({ home, name: node.name }); stopped.push(node.name); } catch (_) {}
+  }
+  if (st && st.rendezvous) {
+    try { nodesTunnel.stopTunnel({ home, name: nodesTunnel.REVERSE_NAME }); stopped.push(nodesTunnel.REVERSE_NAME); } catch (_) {}
+  }
+  return stopped;
+}
+
+function refusePairedPortRelocation(opts, from, to) {
+  if (Number(from) === Number(to)) return;
+  const { configDir } = urlmod.resolvePaths(opts);
+  const nodesPath = opts.nodesPath || path.join(configDir, 'nodes.json');
+  if (nodesStore.hasPairedPeers(nodesStore.loadStore(nodesPath))) {
+    throw new Error(`port ${from} is busy and paired peers exist; refusing automatic move to ${to}. Free the configured port or reconnect peers intentionally.`);
+  }
+}
+
+// Runtime ownership is independent from boot persistence.  With boot disabled,
+// smartUp intentionally launches `serve --pidfile` on Linux/macOS too; lifecycle
+// commands must therefore inspect both the service manager and that portable
+// pidfile instead of assuming the platform selects exactly one owner.
+function managedRuntimeState(opts = {}) {
   const platform = opts.platform || detectPlatform();
   const execImpl = opts.execImpl || execFileSync;
-  const log = opts.log || console.log;
-
   if (platform === 'linux') {
-    execImpl('systemctl', ['--user', 'stop', 'nexuscrew'], { stdio: 'ignore' });
-    log('stop: systemctl --user stop nexuscrew');
-    return { platform, stopped: true };
+    try {
+      const service = String(execImpl('systemctl', ['--user', 'is-active', 'nexuscrew'], { encoding: 'utf8' }) || '').trim();
+      return { supported: true, running: service === 'active', service: service || 'inactive' };
+    } catch (_) { return { supported: true, running: false, service: 'inactive' }; }
   }
   if (platform === 'mac') {
-    const label = `gui/${opts.uid || uid()}/com.mmmbuto.nexuscrew`;
+    const service = `gui/${opts.uid || uid()}/com.mmmbuto.nexuscrew`;
     try {
-      // bootout scarica il job: KeepAlive non puo' rianimare uno stop volontario.
-      execImpl('launchctl', ['bootout', label], { stdio: 'ignore' });
-      log(`stop: launchctl bootout ${label}`);
-      return { platform, stopped: true };
-    } catch (e) {
-      const reason = String(e.message || e);
-      log(`stop: launchctl bootout fallito: ${reason}`);
-      return { platform, stopped: false, reason };
-    }
+      execImpl('launchctl', ['print', service], { stdio: 'ignore' });
+      return { supported: true, running: true, service };
+    } catch (_) { return { supported: true, running: false, service }; }
   }
-  if (platform === 'termux') {
-    // kill via pidfile verificato (no broad match) + wake-lock-release
-    const pidPath = pidf.defaultPidfilePath(opts.home);
-    const r = pidf.killPidfile(pidPath);
-    try { execImpl('termux-wake-lock-release', [], { stdio: 'ignore' }); } catch (_) {}
-    log(`stop: ${r.killed ? `killed pid ${r.pid}` : r.reason}`);
-    return { platform, stopped: r.killed, reason: r.reason };
+  return { supported: false, running: false, service: 'portable-only' };
+}
+
+function portableRuntimeState(opts = {}) {
+  const home = opts.home || require('node:os').homedir();
+  const pidPath = pidf.defaultPidfilePath(home);
+  const meta = pidf.readPidfile(pidPath);
+  if (!meta) return { running: false, pidPath, reason: 'no pidfile' };
+  if (pidf.isAlive(meta)) return { running: true, pidPath, pid: meta.pid, meta };
+  pidf.cleanStale(pidPath);
+  return { running: false, pidPath, reason: 'stale pidfile' };
+}
+
+function resolveRuntimeOwner(opts = {}) {
+  const platform = opts.platform || detectPlatform();
+  const managed = managedRuntimeState({ ...opts, platform });
+  const portable = portableRuntimeState(opts);
+  let owner = 'stopped';
+  if (managed.running && portable.running) owner = 'conflict';
+  else if (managed.running) owner = 'managed';
+  else if (portable.running) owner = 'portable';
+  return {
+    platform, owner,
+    managedRunning: managed.running,
+    portableRunning: portable.running,
+    service: managed.service,
+    portablePid: portable.pid,
+    pidPath: portable.pidPath,
+    stalePidfile: portable.reason === 'stale pidfile',
+    portableReason: portable.reason,
+  };
+}
+
+function waitForPidExit(pid, timeoutMs = 2000) {
+  const deadline = Date.now() + timeoutMs;
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  const exited = () => {
+    if (!pidf.pidExists(pid)) return true;
+    // A test-owned child can remain as a zombie until this synchronous caller
+    // returns to the event loop. It no longer owns sockets and is exited for
+    // lifecycle purposes. Linux/Termux expose the state in /proc; macOS has no
+    // equivalent cheap path and normally removes a non-child immediately.
+    try { return fs.readFileSync(`/proc/${pid}/stat`, 'utf8').split(' ')[2] === 'Z'; }
+    catch (_) { return false; }
+  };
+  while (!exited() && Date.now() < deadline) Atomics.wait(sleeper, 0, 0, 25);
+  return exited();
+}
+
+function stopPortableRuntime(opts = {}) {
+  const home = opts.home || require('node:os').homedir();
+  const pidPath = pidf.defaultPidfilePath(home);
+  const result = pidf.killPidfile(pidPath);
+  if (result.killed && !waitForPidExit(result.pid, opts.stopWaitMs || 2000)) {
+    return { ...result, killed: false, reason: `pid ${result.pid} did not exit after SIGTERM` };
   }
-  throw new Error(`stop: platform ${platform} non supportata`);
+  return result;
 }
 
-// running-check per-platform (no log) — riusato da smart-up / token rotate / update.
-function isServiceRunning(opts = {}) {
+function stop(opts = {}) {
   const platform = opts.platform || detectPlatform();
   const execImpl = opts.execImpl || execFileSync;
-  if (platform === 'linux') {
-    try { return execImpl('systemctl', ['--user', 'is-active', 'nexuscrew'], { encoding: 'utf8' }).trim() === 'active'; }
-    catch (_) { return false; }
+  const log = opts.log || console.log;
+  if (!['linux', 'mac', 'termux'].includes(platform)) throw new Error(`stop: platform ${platform} non supportata`);
+
+  const before = resolveRuntimeOwner({ ...opts, platform, execImpl });
+  const stoppedOwners = [];
+  const errors = [];
+
+  // The shared tmux server can live in the NexusCrew systemd cgroup.  If the
+  // effective KillMode cannot be proven safe, stop must not mutate *any*
+  // runtime owner or detached tunnel: callers can then fix the unit and retry
+  // without ending up in a partially stopped state.
+  if (before.managedRunning && platform === 'linux') {
+    try {
+      (opts.ensureTmuxSurvivalImpl || ensureLinuxTmuxSurvival)({ ...opts, home: opts.home, execImpl });
+    } catch (error) {
+      const reason = String(error.message || error);
+      log(`stop: annullato — protezione tmux non verificata: ${reason}`);
+      return { platform, owner: before.owner, stopped: false, stoppedOwners, reason };
+    }
   }
-  if (platform === 'mac') {
-    try { execImpl('launchctl', ['print', `gui/${opts.uid || uid()}/com.mmmbuto.nexuscrew`], { stdio: 'ignore' }); return true; }
-    catch (_) { return false; }
+
+  if (before.managedRunning) {
+    try {
+      if (platform === 'linux') {
+        execImpl('systemctl', ['--user', 'stop', 'nexuscrew'], { stdio: 'ignore' });
+        log('stop: systemctl --user stop nexuscrew');
+      } else {
+        const label = `gui/${opts.uid || uid()}/com.mmmbuto.nexuscrew`;
+        // bootout unloads KeepAlive, so a voluntary stop stays stopped.
+        execImpl('launchctl', ['bootout', label], { stdio: 'ignore' });
+        log(`stop: launchctl bootout ${label}`);
+      }
+      stoppedOwners.push('managed');
+    } catch (error) { errors.push(String(error.message || error)); }
   }
+
+  if (before.portableRunning) {
+    const portable = (opts.stopPortableImpl || stopPortableRuntime)(opts);
+    if (portable.killed) {
+      stoppedOwners.push('portable');
+      log(`stop: killed portable pid ${portable.pid}`);
+    } else errors.push(portable.reason || 'portable stop failed');
+  }
+
+  // Detached tunnel supervisors are outside both server owners. A real stop
+  // closes them once; the next start restores only autostart:true links.
+  (opts.stopTunnelsImpl || stopManagedTunnels)(opts);
   if (platform === 'termux') {
-    const meta = pidf.readPidfile(pidf.defaultPidfilePath(opts.home));
-    return !!(meta && pidf.isAlive(meta));
+    try { execImpl('termux-wake-lock-release', [], { stdio: 'ignore' }); } catch (_) {}
   }
-  return false;
+
+  if (errors.length) {
+    const reason = errors.join('; ');
+    log(`stop: incompleto — ${reason}`);
+    return { platform, owner: before.owner, stopped: false, stoppedOwners, reason };
+  }
+  const alreadyStopped = before.owner === 'stopped';
+  if (alreadyStopped) log(`stop: ${before.portableReason || 'already stopped'}`);
+  return {
+    platform, owner: before.owner, stopped: true, stoppedOwners, alreadyStopped,
+    reason: alreadyStopped ? (before.portableReason || 'already stopped') : undefined,
+  };
+}
+
+// running-check per-platform (no log) — riusato da smart-up / token rotate / update.
+function isServiceRunning(opts = {}) {
+  return resolveRuntimeOwner(opts).owner !== 'stopped';
 }
 
 function bootState(opts = {}) {
@@ -274,12 +393,13 @@ function quickSummary(result, opts = {}) {
   let cached = [];
   try { cached = (require('../nodes/topology-cache.js').loadCache(opts.topologyCachePath || require('../nodes/topology-cache.js').defaultPath(home)) || {}).nodes || []; } catch (_) {}
   const direct = (st && st.nodes) || [];
-  const online = direct.filter((n) => nodesTunnel.readTunnelState(home, n.name).status === 'up').length;
+  const managed = direct.filter((n) => n.direction !== 'inbound');
+  const online = managed.filter((n) => nodesTunnel.readTunnelState(home, n.name).status === 'up').length;
   const known = direct.length + cached.filter((n) => !direct.some((d) => d.nodeId && d.nodeId === n.instanceId)).length;
   log(`NexusCrew ${require('../../package.json').version}`);
   log(`server  ${result.running ? '● running' : '○ stopped'} · 127.0.0.1:${result.port}`);
   log(`boot    ${bootState({ ...opts, platform }).enabled ? 'on' : 'off'} · ${platform}`);
-  log(`nodes   ${known} known · ${online}/${direct.length} direct tunnels up`);
+  log(`nodes   ${known} known · ${online}/${managed.length} hub connections up`);
   log('');
   log('open    nexuscrew show');
   log('link    nexuscrew show token');
@@ -304,25 +424,18 @@ function status(opts = {}) {
   const { configPath, configDir } = urlmod.resolvePaths(opts);
   const nodesPath = opts.nodesPath || path.join(configDir, 'nodes.json');
 
-  const out = { platform, service: null, running: null, port: null, url: null, roles: null, nodes: [] };
+  const runtime = resolveRuntimeOwner({ ...opts, platform, execImpl });
+  const out = {
+    platform, service: runtime.service, running: runtime.owner !== 'stopped',
+    runtimeOwner: runtime.owner, managedRunning: runtime.managedRunning,
+    portableRunning: runtime.portableRunning, portablePid: runtime.portablePid,
+    port: null, url: null, roles: null, nodes: [],
+  };
 
-  if (platform === 'linux') {
-    try {
-      const s = execImpl('systemctl', ['--user', 'is-active', 'nexuscrew'], { encoding: 'utf8' }).trim();
-      out.service = s; out.running = s === 'active';
-    } catch (_) { out.service = 'inactive'; out.running = false; }
-  } else if (platform === 'mac') {
-    out.service = `gui/${opts.uid || uid()}/com.mmmbuto.nexuscrew`;
-    try {
-      execImpl('launchctl', ['print', out.service], { stdio: 'ignore' });
-      out.running = true;
-    } catch (_) { out.running = false; }
-  } else if (platform === 'termux') {
+  if (platform === 'termux') {
     // boot-script installed vs server running (pidfile vivo)
     const bootScript = path.join(home, '.termux', 'boot', 'nexuscrew.sh');
     out.bootScriptInstalled = fs.existsSync(bootScript);
-    const meta = pidf.readPidfile(pidf.defaultPidfilePath(home));
-    out.running = !!(meta && pidf.isAlive(meta));
     out.service = out.bootScriptInstalled ? 'boot-script installed' : 'no boot-script';
   }
 
@@ -341,8 +454,10 @@ function status(opts = {}) {
         return {
           name: red.name, roles: red.roles,
           remotePort: red.remotePort, localPort: red.localPort,
-          hasToken: red.hasToken,
-          tunnel: nodesTunnel.readTunnelState(home, n.name),
+          direction: red.direction, shared: red.shared, hasToken: red.hasToken,
+          tunnel: n.direction === 'inbound'
+            ? { status: n.shared === true ? 'shared-peer' : 'private-peer', managed: false }
+            : nodesTunnel.readTunnelState(home, n.name),
         };
       });
     }
@@ -354,6 +469,7 @@ function status(opts = {}) {
     log(`platform:  ${out.platform}`);
     log(`service:   ${out.service}`);
     log(`running:   ${out.running}`);
+    log(`runtime:   ${out.runtimeOwner}${out.portablePid ? ` (pid ${out.portablePid})` : ''}`);
     log(`port:      ${out.port}`);
     log(`url:       ${out.url}`);
     log(`roles:     client=${out.roles.client} node=${out.roles.node}`);
@@ -368,23 +484,59 @@ function restart(opts = {}) {
   const platform = opts.platform || detectPlatform();
   const execImpl = opts.execImpl || execFileSync;
   const log = opts.log || console.log;
-  if (platform === 'linux') {
-    execImpl('systemctl', ['--user', 'restart', 'nexuscrew'], { stdio: 'ignore' });
-    log('restart: systemctl --user restart nexuscrew');
-    return { platform, restarted: true };
-  }
-  if (platform === 'mac') {
-    const label = `gui/${opts.uid || uid()}/com.mmmbuto.nexuscrew`;
-    execImpl('launchctl', ['kickstart', '-k', label], { stdio: 'ignore' });
-    log(`restart: launchctl kickstart -k ${label}`);
-    return { platform, restarted: true };
-  }
-  if (platform === 'termux') {
-    stop({ execImpl, log, platform, uid: opts.uid });
-    start({ execImpl, spawnImpl: opts.spawnImpl, log, platform, uid: opts.uid });
-    return { platform, restarted: true };
+  if (!['linux', 'mac', 'termux'].includes(platform)) throw new Error(`restart: platform ${platform} non supportata`);
+  const before = resolveRuntimeOwner({ ...opts, platform, execImpl });
+
+  // A managed owner can use the service manager's atomic restart. In a
+  // conflict, first remove only the stray portable owner, then keep managed as
+  // the single authority.
+  if (before.managedRunning) {
+    if (platform === 'linux') {
+      try {
+        (opts.ensureTmuxSurvivalImpl || ensureLinuxTmuxSurvival)({ ...opts, home: opts.home, execImpl });
+      } catch (error) {
+        return { platform, owner: before.owner, runtimeOwner: 'managed', restarted: false, reason: String(error.message || error) };
+      }
+    }
+    if (before.portableRunning) {
+      const portable = (opts.stopPortableImpl || stopPortableRuntime)(opts);
+      if (!portable.killed) return { platform, owner: before.owner, restarted: false, reason: portable.reason };
+    }
+    try {
+      if (platform === 'linux') {
+        (opts.stopTunnelsImpl || stopManagedTunnels)(opts);
+        execImpl('systemctl', ['--user', 'restart', 'nexuscrew'], { stdio: 'ignore' });
+        log('restart: systemctl --user restart nexuscrew');
+      } else {
+        (opts.stopTunnelsImpl || stopManagedTunnels)(opts);
+        const label = `gui/${opts.uid || uid()}/com.mmmbuto.nexuscrew`;
+        execImpl('launchctl', ['kickstart', '-k', label], { stdio: 'ignore' });
+        log(`restart: launchctl kickstart -k ${label}`);
+      }
+      return { platform, owner: before.owner, runtimeOwner: 'managed', restarted: true };
+    } catch (error) {
+      return { platform, owner: before.owner, runtimeOwner: 'managed', restarted: false, reason: String(error.message || error) };
+    }
   }
-  throw new Error(`restart: platform ${platform} non supportata`);
+
+  if (before.portableRunning) {
+    const stopped = stop({ ...opts, platform, execImpl, log });
+    if (!stopped.stopped) return { platform, owner: before.owner, restarted: false, reason: stopped.reason };
+    const started = (opts.startPortableImpl || startPortable)({ ...opts, platform, spawnImpl: opts.spawnImpl });
+    const ok = !!(started && started.started !== false);
+    if (ok) log('restart: portable runtime started');
+    return { platform, owner: before.owner, runtimeOwner: 'portable', restarted: ok, reason: ok ? undefined : started && started.reason };
+  }
+
+  // `restart` on a stopped runtime follows the explicit boot owner; with boot
+  // disabled it starts a portable background runtime.
+  const useManaged = platform !== 'termux' && bootState({ ...opts, platform, execImpl }).enabled;
+  const started = useManaged
+    ? start({ ...opts, platform, execImpl, spawnImpl: opts.spawnImpl, log })
+    : (opts.startPortableImpl || startPortable)({ ...opts, platform, spawnImpl: opts.spawnImpl });
+  const ok = !!(started && started.started !== false);
+  if (ok) log(`restart: ${useManaged ? 'managed' : 'portable'} runtime started`);
+  return { platform, owner: before.owner, runtimeOwner: useManaged ? 'managed' : 'portable', restarted: ok, reason: ok ? undefined : started && started.reason };
 }
 
 function wizardComplete(configPath) {
@@ -446,6 +598,8 @@ async function waitForNexusCrew(port, token, opts = {}) {
 function startPortable(opts = {}) {
   const spawnImpl = opts.spawnImpl || spawn;
   const home = opts.home || require('node:os').homedir();
+  const existing = portableRuntimeState({ home });
+  if (existing.running) return { started: false, reason: 'already running', pid: existing.pid, portable: true };
   const logPath = path.join(home, '.nexuscrew', 'nexuscrew.log');
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
   const logFd = fs.openSync(logPath, 'a');
@@ -502,6 +656,7 @@ async function smartUp(opts = {}) {
   if (!initialized) {
     const requested = opts.port || urlmod.loadPort(opts);
     const selected = await findAvailablePort(requested, opts);
+    refusePairedPortRelocation(opts, requested, selected);
     runInitImpl({ ...opts, port: selected, log: quiet, platform, installBoot: false, printUrl: false });
     port = selected;
     initialized = true;
@@ -519,19 +674,24 @@ async function smartUp(opts = {}) {
   let token = urlmod.readToken(tokenPath);
   let running = await probe(port, token, opts);
   let portableAttempted = false;
-  const managedRunning = isServiceRunning({ ...opts, platform });
-  if (!running && managedRunning) running = await waitForNexusCrew(port, token, opts);
+  let runtime = resolveRuntimeOwner({ ...opts, platform });
+  if (!running && runtime.owner !== 'stopped') running = await waitForNexusCrew(port, token, opts);
 
   if (!running) {
     if (!(await (opts.portAvailableImpl || portAvailable)(port, '127.0.0.1'))) {
+      const previousPort = port;
       port = await findAvailablePort(port + 1, opts);
+      refusePairedPortRelocation(opts, previousPort, port);
       runInitImpl({ ...opts, port, log: quiet, platform, installBoot: persistent, printUrl: false });
       token = urlmod.readToken(tokenPath);
     } else {
       try {
-        const started = persistent
-          ? (managedRunning ? restartImpl({ ...opts, platform, log: quiet }) : startImpl({ ...opts, platform, log: quiet }))
-          : portableStart({ ...opts, platform });
+        runtime = resolveRuntimeOwner({ ...opts, platform });
+        const started = runtime.owner === 'conflict'
+          ? restartImpl({ ...opts, platform, log: quiet })
+          : persistent
+            ? (runtime.managedRunning ? restartImpl({ ...opts, platform, log: quiet }) : startImpl({ ...opts, platform, log: quiet }))
+            : (runtime.portableRunning ? restartImpl({ ...opts, platform, log: quiet }) : portableStart({ ...opts, platform }));
         if (started && started.started === false) {
           portableStart({ ...opts, platform }); portableAttempted = true;
         }
@@ -572,17 +732,34 @@ function url(opts = {}) {
 function tokenRotate(opts = {}) {
   const log = opts.log || console.log;
   const platform = opts.platform || detectPlatform();
+  const execImpl = opts.execImpl || execFileSync;
   const { tokenPath } = urlmod.resolvePaths(opts);
   const readonly = process.env.NEXUSCREW_READONLY === '1' || opts.readonly;
   if (readonly) {
     log('token rotate: READONLY, rotazione bloccata');
     return { rotated: false, reason: 'readonly' };
   }
+  const runtime = resolveRuntimeOwner({ ...opts, platform, execImpl });
+  const running = runtime.owner !== 'stopped';
+  if (runtime.managedRunning && platform === 'linux') {
+    try {
+      (opts.ensureTmuxSurvivalImpl || ensureLinuxTmuxSurvival)({ ...opts, home: opts.home, execImpl });
+    } catch (error) {
+      const reason = String(error.message || error);
+      log(`token rotate: annullata — protezione tmux non verificata: ${reason}`);
+      return { rotated: false, tokenWritten: false, restarted: false, running, reason };
+    }
+  }
   rotateToken(tokenPath); // atomico (tmp+rename, 0600, no-symlink); non stampa il token
   log(`token: nuovo segreto scritto (${tokenPath})`);
-  const running = isServiceRunning({ ...opts, platform });
   if (running) {
-    restart({ ...opts, platform, log });
+    const restarted = (opts.restartImpl || restart)({ ...opts, platform, execImpl, log });
+    if (!restarted || restarted.restarted !== true) {
+      const reason = (restarted && restarted.reason) || 'esito restart non verificato';
+      log(`token rotate: INCOMPLETA — nuovo token scritto ma restart fallito: ${reason}`);
+      log('token rotate: non e\' possibile confermare l\'invalidazione del vecchio token; correggi il servizio e ripeti il restart');
+      return { rotated: false, tokenWritten: true, restarted: false, running, reason };
+    }
     log('token rotate: servizio riavviato — vecchio token invalidato (401), nuovo attivo (200)');
   } else {
     // il service manager non lo vede, ma un `serve` manuale (pidfile) puo' essere
@@ -594,8 +771,8 @@ function tokenRotate(opts = {}) {
       log('token rotate: servizio non attivo (il nuovo token varra\' al prossimo start)');
     }
   }
-  log('usa `nexuscrew url` per il nuovo URL (il token non si stampa qui)');
-  return { rotated: true, running };
+  log('usa `nexuscrew show token` per il nuovo URL (il token non si stampa qui)');
+  return { rotated: true, tokenWritten: true, restarted: running, running };
 }
 
 // logs [-f]: passthrough. linux -> journalctl --user -u nexuscrew; mac/termux -> logfile.
@@ -642,12 +819,17 @@ function update(opts = {}) {
   }
   const running = isServiceRunning({ ...opts, platform });
   if (running) {
-    restart({ ...opts, platform, log });
+    const restarted = (opts.restartImpl || restart)({ ...opts, platform, log });
+    if (!restarted || restarted.restarted !== true) {
+      const reason = (restarted && restarted.reason) || 'esito restart non verificato';
+      log(`update: pacchetto installato ma restart fallito — ${reason}`);
+      return { updated: true, running, restarted: false, reason, code: 1 };
+    }
     log('update: servizio riavviato sul nuovo codice');
   } else {
     log('update: servizio non attivo (nessun restart)');
   }
-  return { updated: true, running, code: 0 };
+  return { updated: true, running, restarted: running, code: 0 };
 }
 
 // B4.3 — fleet-boot companion: avvia le celle boot:true del provider selezionato.
@@ -703,7 +885,7 @@ function dispatch(argv, opts = {}) {
     log(require('../../package.json').version);
     return { code: 0 };
   }
-  const { flags, rest } = parseFlags(argv, VALUE_FLAGS);
+  const { flags, rest } = parseFlags(argv);
   const cmd = rest[0];
 
   // help esplicito
@@ -742,6 +924,18 @@ function dispatch(argv, opts = {}) {
     log(require('../../package.json').version);
     return { code: 0 };
   }
+  if (cmd === 'status') {
+    status({ ...opts, log });
+    return { code: 0 };
+  }
+  if (cmd === 'stop') {
+    const result = stop({ ...opts, log });
+    return { code: result.stopped || ['not running', 'stale pidfile'].includes(result.reason) ? 0 : 1 };
+  }
+  if (cmd === 'restart') {
+    const result = restart({ ...opts, log });
+    return { code: result.restarted ? 0 : 1 };
+  }
   // Internal runtime commands used by service managers and MCP clients. They
   // are intentionally omitted from HELP and are not configuration surfaces.
   if (cmd === 'serve') {
@@ -766,62 +960,6 @@ function dispatch(argv, opts = {}) {
   return { code: 1 };
 }
 
-// nodes add|list|remove|test|up|down|restart|set-token (design §3, §4).
-function dispatchNodes(rest, flags, opts) {
-  const log = opts.log;
-  const sub = rest[1];
-  const name = rest[2];
-  const common = { ...opts, name };
-  switch (sub) {
-    case 'add':
-      return { code: nodesCmds.nodesAdd({
-        ...common, ssh: flags.ssh, sshPort: flags['ssh-port'], remotePort: flags['remote-port'],
-        key: flags.key, localPort: flags['local-port'], nodeId: flags['node-id'],
-      }).code };
-    case undefined:
-    case 'list':
-      return { code: nodesCmds.nodesList({ ...opts, json: !!flags.json }).code };
-    case 'remove':
-      return { code: nodesCmds.nodesRemove(common).code };
-    case 'up':
-      return { code: nodesCmds.nodesUp(common).code };
-    case 'down':
-      return { code: nodesCmds.nodesDown(common).code };
-    case 'restart':
-      return { code: nodesCmds.nodesRestart(common).code };
-    case 'set-token':
-      return { code: nodesCmds.nodesSetToken(common).code };
-    case 'test': {
-      // async: tieni vivo il processo finche' il probe non risolve, poi exit.
-      const exit = typeof opts.exit === 'function' ? opts.exit : ((c) => process.exit(c));
-      nodesCmds.nodesTest(common)
-        .then((r) => exit(r.code))
-        .catch((e) => { log(`nodes test: error — ${e && e.message ? e.message : e}`); exit(1); });
-      return { code: 0, keepAlive: true };
-    }
-    default:
-      log('usage: nexuscrew nodes add|list|remove|test|up|down|restart|set-token <name>');
-      return { code: 1 };
-  }
-}
-
-// node on|off — ruolo "nodo raggiungibile" (reverse tunnel). §4.
-function dispatchNode(rest, flags, opts) {
-  const log = opts.log;
-  const sub = rest[1];
-  if (sub === 'on') {
-    return { code: nodesCmds.nodeOn({
-      ...opts, rendezvousSsh: flags.rendezvous,
-      publishedPort: flags['published-port'], key: flags.key,
-    }).code };
-  }
-  if (sub === 'off') {
-    return { code: nodesCmds.nodeOff({ ...opts }).code };
-  }
-  log('usage: nexuscrew node on|off');
-  return { code: 1 };
-}
-
 module.exports = {
   dispatch, serve, start, stop, status, parseFlags, HELP,
   smartUp, url, tokenRotate, logs, doctor, update, restart,
@@ -829,5 +967,7 @@ module.exports = {
   servicePinsLegacyPort,
   isServiceRunning, readRoles,
   bootState, bootOn, bootOff, quickSummary,
+  stopManagedTunnels,
+  managedRuntimeState, portableRuntimeState, resolveRuntimeOwner,
   runFleetBoot, dispatchFleetBoot,
 };