@remcp/remcp 0.2.46 → 0.2.48

package/README.md

@@ -17,8 +17,8 @@ credential under `~/.config/remcp/`, installs the runtime from npm, and register
 ## Commands
 
 ```text
-remcp start                  Run the device agent in the foreground
-remcp status                 Show version, pairing, runtime, telemetry and server health as JSON
+remcp start                  Run the device agent when no managed background service is already running
+remcp status                 Show device/agent versions, update consistency and server reachability as JSON
 remcp doctor                 Same report plus a real tool handshake with the local runtime, and which
                              macOS privacy folders (Desktop, Documents, Downloads, iCloud Drive) this
                              computer currently lets ReMCP use
@@ -31,8 +31,7 @@ remcp godmode [status|on|off]
 remcp --version
 ```
 
-`remcp status` reports the runtime the device would install, whether the agent service is running,
-and the current usage-metrics state, so a support request can be answered with one paste.
+`remcp status` reports the configured/installed runtime, the managed-agent state, whether multiple local ReMCP installations are consistent, whether an update is required, server reachability, and the current usage-metrics state. It deliberately does not expose backend database/provider, relay topology, fleet size, or other operational internals. `remcp doctor` adds local runtime/filesystem diagnostics, so a support request can still be answered with one paste.
 
 ## Unrestricted mode
 
@@ -66,11 +65,15 @@ permission, and `remcp doctor` reports the state of each one.
 
 ## Updates
 
-The agent asks the server which versions it should run when it connects and every six hours, installs
-a newer client and runtime in the background, and restarts the service so they take effect. A failed
-install is retried no more often than every thirty minutes, so a broken release cannot turn into an
-install loop. `remcp update` does the same immediately; `remcp auto-update off` turns the automatic
-check off for a machine that must not change on its own.
+The agent asks the server which versions it should run on every successful connection and every six hours, installs the exact trusted client/runtime release pair in the background, and restarts the managed service so it takes effect. The updater resolves itself and the sibling runtime from the package that is actually running instead of depending on an interactive shell PATH. When the same computer has been used from more than one Node manager (for example NVM plus Hermes/FNM/Homebrew), ReMCP keeps the canonical service installation stable and converges the known local installations on the same release pair. `remcp status` reports mixed installations instead of hiding the skew. A failed install is retried no more often than every thirty minutes and update-check failures are logged, so a broken release cannot become a silent install loop. `remcp update` does the same immediately; `remcp auto-update off` disables automatic checks.
+
+## Computer-use routing
+
+When an AI host controls a visible application, ReMCP is designed for semantic targeting rather than screenshot-coordinate loops:
+
+`Accessibility/UI Automation → browser DOM/CDP → OCR → coordinates`
+
+Use `computer_snapshot` for an unfamiliar state, native `ui_*` tools for desktop applications, and `browser_*` tools for debuggable Chromium page content. `browser_navigate action=new_tab` can create the first page target when the debug browser has none. `type_text` with its default `method=auto` is for exact Unicode text; `keyboard` is for shortcuts and navigation/control keys. `type_text method=keys` emits physical keys and therefore follows the computer's active keyboard layout. Prefer `wait_for_ui` or `browser_wait` to fixed sleeps and use `screenshot_region` only when pixel/layout verification adds information. For PDF/DOCX/XLSX content, use the structured document tools before automating Office applications.
 
 ## Screenshots
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/remcp",
-  "version": "0.2.46",
+  "version": "0.2.48",
   "description": "ReMCP device client: pair a computer with ReMCP and run the outbound-only agent that hosts the local MCP runtime.",
   "type": "module",
   "license": "MIT",

package/src/agent-update.mjs

@@ -2,11 +2,23 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { resolveNpm } from './npm.mjs';
 import { isRuntimeSpecFor, normalizeRuntime } from './runtime.mjs';
 import { PACKAGE_NAME, VERSION } from './version.mjs';
 
 const npm = resolveNpm();
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PACKAGE_CLI_ENTRY = path.join(PACKAGE_ROOT, 'bin', 'remcp.mjs');
+const PACKAGE_MANIFEST = path.join(PACKAGE_ROOT, 'package.json');
+
+function packageLocalNodeModules() {
+  const marker = `${path.sep}node_modules${path.sep}`;
+  const index = PACKAGE_ROOT.lastIndexOf(marker);
+  if (index < 0) return null;
+  return PACKAGE_ROOT.slice(0, index + `${path.sep}node_modules`.length);
+}
+
 // How long a handing-over agent waits for its replacement to take the device over before it keeps
 // running itself. Long enough for a fresh process to connect and be registered.
 const REPLACEMENT_HANDOVER_TIMEOUT_MS = 20_000;
@@ -19,6 +31,11 @@ function globalNodeModules() {
 
 export function localRuntimeEntry(runtimeValue) {
   const runtime = normalizeRuntime(runtimeValue);
+  const localModules = packageLocalNodeModules();
+  if (localModules) {
+    const sibling = path.join(localModules, ...runtime.packageName.split('/'), ...runtime.entry.split(/[\\/]+/));
+    if (existsSync(sibling)) return sibling;
+  }
   const candidate = path.join(globalNodeModules(), ...runtime.packageName.split('/'), ...runtime.entry.split(/[\\/]+/));
   if (!existsSync(candidate)) throw new Error('ReMCP local runtime is not installed. Run `remcp install`.');
   return candidate;
@@ -31,7 +48,7 @@ function parseVersion(value) {
   return match ? { parts: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4] || '' } : null;
 }
 
-function isNewer(candidate, current) {
+export function isNewer(candidate, current) {
   const a = parseVersion(candidate);
   const b = parseVersion(current);
   if (!a || !b) return false;
@@ -142,7 +159,11 @@ export async function restartToApplyUpdate(cli, stopAgent, markStopping, onRunti
 // The version of the globally installed client, read from the package the CLI resolves to.
 export function globalInstalledVersion() {
   try {
-    const cli = globalCliEntry();
+    try {
+      const local = JSON.parse(readFileSync(PACKAGE_MANIFEST, 'utf8')).version;
+      if (local) return local;
+    } catch {}
+    const cli = globalCliEntry({ packageLocal:false });
     if (!cli) return null;
     const base = path.dirname(cli);
     const candidates = [
@@ -182,8 +203,12 @@ export function supervisorRestart({ platform = process.platform, dockerenv = exi
   return null;
 }
 
-export function globalCliEntry() {
-  const prefix = spawnSync(npm.command, [...npm.args, 'prefix', '--global'], { encoding: 'utf8' });
+export function globalCliEntry({ packageLocal = true } = {}) {
+  // The running agent already knows exactly which @remcp/remcp package owns it. Prefer the sibling
+  // CLI entry and avoid asking npm which global prefix happens to be active in a minimal service
+  // environment (FNM/NVM/Hermes/Homebrew can all disagree with the shell).
+  if (packageLocal && existsSync(PACKAGE_CLI_ENTRY)) return PACKAGE_CLI_ENTRY;
+  const prefix = spawnSync(npm.command, [...npm.args, 'prefix', '--global'], { encoding:'utf8' });
   if (prefix.error || prefix.status !== 0) return null;
   const base = String(prefix.stdout || '').trim();
   return process.platform === 'win32'

package/src/agent.mjs

@@ -84,6 +84,7 @@ export async function runAgent(options) {
   let runtimeVersion = 'unknown';
   let runtimeRestarts = 0;
   let runtimeDown = false;
+  let runtimeTools = [];
   // The reason the runtime is not running, sent to the server so the workspace can show something
   // actionable instead of a machine that merely looks connected.
   let runtimeError = '';
@@ -119,6 +120,25 @@ export async function runAgent(options) {
     return env;
   }
 
+  function toolNames(listed) {
+    const tools = Array.isArray(listed?.tools) ? listed.tools : [];
+    return [...new Set(tools.map(tool => String(tool?.name || '').trim().slice(0, 128)).filter(Boolean))].slice(0, 256);
+  }
+
+  async function refreshRuntimeTools(client = mcp, { announce = true } = {}) {
+    if (!client || runtimeDown) return runtimeTools;
+    try {
+      const listed = await client.listTools(undefined, { timeout: 3000 });
+      const next = toolNames(listed);
+      if (next.length === runtimeTools.length && next.every((name, index) => name === runtimeTools[index])) return runtimeTools;
+      runtimeTools = next;
+      if (announce) send({ type: 'capabilities', runtimeTools });
+    } catch (error) {
+      console.error(`ReMCP could not refresh runtime capabilities: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return runtimeTools;
+  }
+
   async function startRuntime() {
     if (stopping) return;
     clearTimeout(runtimeRestartTimer);
@@ -139,6 +159,10 @@ export async function runAgent(options) {
     mcp = client;
     transport = stdio;
     client.fallbackNotificationHandler = async notification => {
+      if (notification?.method === 'notifications/tools/list_changed') {
+        await refreshRuntimeTools(client);
+        return;
+      }
       if (!telemetryEnabled) return;
       if (notification?.method !== 'notifications/remcp/telemetry') return;
       const events = Array.isArray(notification.params?.events) ? notification.params.events : [];
@@ -159,6 +183,7 @@ export async function runAgent(options) {
       runtimeRestartDelay = RUNTIME_RESTART_BASE_MS;
       runtimeDown = false;
       runtimeError = '';
+      await refreshRuntimeTools(client);
       console.log(`ReMCP local runtime ready (${runtimeVersion})`);
       send({ type: 'metrics', runtimeState: 'ready', runtimeError: '', metrics: deviceMetrics({ reconnects, pendingRequests, runtimeVersion, runtimeRestarts, runtimeDown: false }) });
       if (runtimeRestarts > 1) queueEvent({ event: 'runtime_restart', at: Date.now(), count: runtimeRestarts, success: true });
@@ -173,6 +198,8 @@ export async function runAgent(options) {
   function handleRuntimeExit(reason) {
     if (stopping || runtimeRestartTimer) return;
     runtimeDown = true;
+    runtimeTools = [];
+    send({ type: 'capabilities', runtimeTools });
     const delay = jitter(runtimeRestartDelay);
     runtimeRestartDelay = Math.min(RUNTIME_RESTART_MAX_MS, runtimeRestartDelay * 2);
     console.error(`ReMCP local runtime ${reason}; restarting in ${delay}ms`);
@@ -286,6 +313,15 @@ export async function runAgent(options) {
         // Service access is a user-controlled pause, not an outage. Poll slowly enough not to hammer
         // the relay, but cap recovery so an enable action becomes effective within seconds.
         scheduleReconnect(jitter(RECONNECT_BASE_MS));
+        return;
+      }
+      const status = Number(response.statusCode || 0);
+      const transientHandshakeFailure = status === 408 || status === 425 || status === 429 || (status >= 500 && status <= 599);
+      if (transientHandshakeFailure && !revoked) {
+        // A reverse proxy or relay deploy can refuse the HTTP upgrade before a WebSocket exists.
+        // With an unexpected-response listener the client does not reliably emit close afterwards,
+        // so this branch must schedule its own retry or a still-running agent can stay offline forever.
+        scheduleBackoffReconnect();
       }
     });
     activeSocket = ws;
@@ -306,6 +342,7 @@ export async function runAgent(options) {
         runtimeVersion,
         runtimeState: runtimeDown ? 'down' : 'ready',
         runtimeError,
+        runtimeTools,
         telemetryEnabled,
         reconnects,
       }));
@@ -371,6 +408,8 @@ export async function runAgent(options) {
   let updateInFlight = false;
   let lastAttemptedVersion = '';
   let lastAttemptAt = 0;
+  let lastUpdateCheckError = '';
+  let lastUpdateCheckErrorAt = 0;
   async function checkForUpdate() {
     if (options.autoUpdate === false) return;
     if (updateInFlight) return;
@@ -451,8 +490,17 @@ export async function runAgent(options) {
         console.error(`remcp update could not start: ${error.message}`);
       });
       child.unref();
-    } catch {
-      // Offline, DNS failure, older server without the endpoint: keep running as-is.
+    } catch (error) {
+      // Update discovery must never take the agent offline, but swallowing the exception made FNM/
+      // launchd failures impossible to diagnose. Log only when the reason changes or every 30 min.
+      const message = error instanceof Error ? error.message : String(error);
+      const now = Date.now();
+      if (message !== lastUpdateCheckError || now - lastUpdateCheckErrorAt >= UPDATE_RETRY_COOLDOWN_MS) {
+        console.error(`ReMCP auto-update check failed: ${message}`);
+        lastUpdateCheckError = message;
+        lastUpdateCheckErrorAt = now;
+      }
+      queueEvent({ event:'agent_update', at:now, reason:'check-failed', success:false, errorClass:error?.name || 'Error' });
     }
   }
 

package/src/cli/env.mjs

@@ -11,6 +11,7 @@ export const configFile = path.join(configDir, 'config.json');
 export const runtimeConfigFile = path.join(configDir, 'runtime.json');
 export const machineIdFile = path.join(configDir, 'machine-id');
 export const linuxServiceFile = path.join(home, '.config', 'systemd', 'user', 'remcp-agent.service');
+export const linuxServiceLauncherFile = path.join(configDir, 'remcp-agent-launcher');
 export const macServiceLabel = 'com.remcp.agent';
 export const macServiceFile = path.join(home, 'Library', 'LaunchAgents', `${macServiceLabel}.plist`);
 export const macLogFile = path.join(home, 'Library', 'Logs', 'remcp-agent.log');

package/src/cli/service.mjs

@@ -5,10 +5,11 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
+import { resolveNpm } from '../npm.mjs';
 import { PACKAGE_NAME, VERSION } from '../version.mjs';
 
 import { saveConfig } from './config.mjs';
-import { configDir, home, linuxServiceFile, macLogFile, macServiceFile, macServiceLabel, npm, windowsTaskName } from './env.mjs';
+import { configDir, home, linuxServiceFile, linuxServiceLauncherFile, macLogFile, macServiceFile, macServiceLabel, npm, windowsTaskName } from './env.mjs';
 import { output, run } from './shell.mjs';
 
 export function servicePlatform() {
@@ -28,16 +29,37 @@ export function npmGlobalInstall(...specs) {
   run(npm.command, [...npm.args, 'install', '--global', ...specs, '--no-audit', '--no-fund', '--loglevel=error']);
 }
 
+export function npmGlobalInstallForNode(nodePath, ...specs) {
+  const resolved = resolveNpm({ nodePath, home, platform:servicePlatform() });
+  run(resolved.command, [...resolved.args, 'install', '--global', ...specs, '--no-audit', '--no-fund', '--loglevel=error']);
+}
+
 export function quoteSystemd(value) {
   return `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
 }
 
+function resolvedCliScript(cliPath) {
+  return fs.existsSync(cliPath) ? fs.realpathSync(cliPath) : path.resolve(cliPath);
+}
+
+function writeLinuxServiceLauncher(cliPath = globalCliPath(), nodePath = process.execPath) {
+  const cliScript = resolvedCliScript(cliPath);
+  const launcher = `#!/bin/sh\nexec ${shellQuote(nodePath)} ${shellQuote(cliScript)} \"$@\"\n`;
+  fs.mkdirSync(path.dirname(linuxServiceLauncherFile), { recursive: true, mode: 0o700 });
+  const temporary = `${linuxServiceLauncherFile}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, launcher, { mode: 0o700 });
+  fs.chmodSync(temporary, 0o700);
+  fs.renameSync(temporary, linuxServiceLauncherFile);
+  return linuxServiceLauncherFile;
+}
+
 export function xmlEscape(value) {
   return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
 }
 
-export function installLinuxService(cliPath = globalCliPath()) {
-  const unit = `[Unit]\nDescription=ReMCP device agent\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nExecStart=${quoteSystemd(cliPath)} start\nRestart=always\nRestartSec=3\nNoNewPrivileges=true\n\n[Install]\nWantedBy=default.target\n`;
+export function installLinuxService(cliPath = globalCliPath(), nodePath = process.execPath) {
+  const launcherFile = writeLinuxServiceLauncher(cliPath, nodePath);
+  const unit = `[Unit]\nDescription=ReMCP device agent\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nExecStart=${quoteSystemd(launcherFile)} start --service\nRestart=always\nRestartSec=3\nNoNewPrivileges=true\n\n[Install]\nWantedBy=default.target\n`;
   fs.mkdirSync(path.dirname(linuxServiceFile), { recursive: true });
   fs.writeFileSync(linuxServiceFile, unit);
   run('systemctl', ['--user', 'daemon-reload']);
@@ -53,12 +75,12 @@ function shellQuote(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }
 
-function macServicePlist(cliPath) {
+function macServicePlist(cliPath, nodePath = process.execPath) {
   // launchd wants an absolute path; a symlinked prefix that npm has not materialised yet (or a path
   // that is about to be replaced by the next install) must not abort the repair — a stale plist is
   // exactly the loop this function exists to break.
   const cliScript = fs.existsSync(cliPath) ? fs.realpathSync(cliPath) : path.resolve(cliPath);
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${macServiceLabel}</string>\n<key>ProgramArguments</key><array><string>${xmlEscape(process.execPath)}</string><string>${xmlEscape(cliScript)}</string><string>start</string></array>\n<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>\n<key>ProcessType</key><string>Background</string>\n<key>StandardOutPath</key><string>${xmlEscape(macLogFile)}</string>\n<key>StandardErrorPath</key><string>${xmlEscape(macLogFile)}</string>\n</dict></plist>\n`;
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${macServiceLabel}</string>\n<key>ProgramArguments</key><array><string>${xmlEscape(nodePath)}</string><string>${xmlEscape(cliScript)}</string><string>start</string><string>--service</string></array>\n<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>\n<key>ProcessType</key><string>Background</string>\n<key>StandardOutPath</key><string>${xmlEscape(macLogFile)}</string>\n<key>StandardErrorPath</key><string>${xmlEscape(macLogFile)}</string>\n</dict></plist>\n`;
 }
 
 function macJobLoaded(target) {
@@ -102,10 +124,10 @@ function scheduleMacServiceRestart(target) {
   ]);
 }
 
-export function installMacService(cliPath = globalCliPath(), { restart = true } = {}) {
+export function installMacService(cliPath = globalCliPath(), { restart = true, nodePath = process.execPath } = {}) {
   const domain = macLaunchDomain();
   const target = `${domain}/${macServiceLabel}`;
-  const plist = macServicePlist(cliPath);
+  const plist = macServicePlist(cliPath, nodePath);
   let previous = '';
   try { previous = fs.readFileSync(macServiceFile, 'utf8'); } catch {}
   const loaded = macJobLoaded(target);
@@ -136,7 +158,7 @@ export function installMacService(cliPath = globalCliPath(), { restart = true }
 }
 
 export function installWindowsService(cliPath = globalCliPath()) {
-  const command = `"${cliPath}" start`;
+  const command = `"${cliPath}" start --service`;
   run('schtasks.exe', ['/Create', '/TN', windowsTaskName, '/TR', command, '/SC', 'ONLOGON', '/RL', 'HIGHEST', '/F']);
   run('schtasks.exe', ['/Run', '/TN', windowsTaskName]);
 }
@@ -157,6 +179,175 @@ export function persistentServiceExpected(config) {
   return false;
 }
 
+export function persistentServiceState(config) {
+  const platform = servicePlatform();
+  const expected = persistentServiceExpected(config);
+  if (platform === 'linux') {
+    const installed = fs.existsSync(linuxServiceFile);
+    const active = installed && spawnSync('systemctl', ['--user', 'is-active', '--quiet', 'remcp-agent.service'], { stdio: 'ignore' }).status === 0;
+    return { expected, installed, active, manager:'systemd-user', name:'remcp-agent.service' };
+  }
+  if (platform === 'darwin') {
+    const installed = fs.existsSync(macServiceFile);
+    const target = typeof process.getuid === 'function' ? 'gui/' + process.getuid() + '/' + macServiceLabel : macServiceLabel;
+    const active = installed && spawnSync('launchctl', ['print', target], { stdio: 'ignore' }).status === 0;
+    return { expected, installed, active, manager:'launchd', name:macServiceLabel };
+  }
+  if (platform === 'win32') {
+    const query = spawnSync('schtasks.exe', ['/Query', '/TN', windowsTaskName, '/FO', 'LIST'], { encoding:'utf8' });
+    const installed = query.status === 0;
+    const outputText = String(query.stdout || '');
+    const active = installed && /(?:Status|Состояние):\s*Running/i.test(outputText);
+    return { expected, installed, active, manager:'schtasks', name:windowsTaskName };
+  }
+  return { expected:false, installed:false, active:false, manager:null, name:null };
+}
+
+function inferServiceIdentity() {
+  const platform = servicePlatform();
+  if (platform === 'linux' && fs.existsSync(linuxServiceLauncherFile)) {
+    try {
+      const body = fs.readFileSync(linuxServiceLauncherFile, 'utf8');
+      const match = body.match(/^exec\s+'([^']+)'\s+'([^']+)'/m);
+      if (match) return { nodePath:match[1], cliPath:match[2] };
+    } catch {}
+  }
+  if (platform === 'darwin' && fs.existsSync(macServiceFile)) {
+    try {
+      const body = fs.readFileSync(macServiceFile, 'utf8');
+      const args = [...body.matchAll(/<string>([^<]+)<\/string>/g)].map(match => match[1]);
+      const startIndex = args.indexOf('start');
+      if (startIndex >= 2) return { nodePath:args[startIndex - 2], cliPath:args[startIndex - 1] };
+    } catch {}
+  }
+  return {};
+}
+
+function canonicalServiceCliPath(config) {
+  const configured = String(config?.serviceCliPath || '').trim();
+  if (configured && fs.existsSync(configured)) return configured;
+  const inferred = inferServiceIdentity().cliPath;
+  if (inferred && fs.existsSync(inferred)) return inferred;
+  return globalCliPath();
+}
+
+function canonicalServiceNodePath(config) {
+  const configured = String(config?.serviceNodePath || '').trim();
+  if (configured && fs.existsSync(configured)) return configured;
+  const inferred = inferServiceIdentity().nodePath;
+  if (inferred && fs.existsSync(inferred)) return inferred;
+  return process.execPath;
+}
+
+function versionFromPackageJson(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return typeof parsed.version === 'string' ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function packageVersionBesideCli(cliPath, packageName) {
+  if (!cliPath || !packageName) return null;
+  const marker = path.sep + 'node_modules' + path.sep;
+  const index = cliPath.lastIndexOf(marker);
+  if (index < 0) return null;
+  const nodeModules = cliPath.slice(0, index + (path.sep + 'node_modules').length);
+  return versionFromPackageJson(path.join(nodeModules, ...String(packageName).split('/'), 'package.json'));
+}
+
+export function installationVersionsAtCliPath(cliPath, runtimePackageName) {
+  if (!cliPath) return { cliVersion:null, runtimeVersion:null, cliPath:null };
+  let resolvedCliPath = cliPath;
+  try { if (fs.existsSync(cliPath)) resolvedCliPath = fs.realpathSync(cliPath); } catch {}
+  return {
+    cliVersion:packageVersionBesideCli(resolvedCliPath, PACKAGE_NAME),
+    runtimeVersion:packageVersionBesideCli(resolvedCliPath, runtimePackageName),
+    cliPath:resolvedCliPath,
+  };
+}
+
+export function serviceInstallationInfo(config) {
+  if (!persistentServiceExpected(config)) return { cliVersion:null, runtimeVersion:null, cliPath:null, nodePath:null };
+  const cliPath = canonicalServiceCliPath(config);
+  const nodePath = canonicalServiceNodePath(config);
+  let resolvedCliPath = cliPath;
+  try { if (cliPath && fs.existsSync(cliPath)) resolvedCliPath = fs.realpathSync(cliPath); } catch {}
+  return {
+    cliVersion:packageVersionBesideCli(resolvedCliPath, PACKAGE_NAME),
+    runtimeVersion:packageVersionBesideCli(resolvedCliPath, config?.runtime?.packageName),
+    cliPath:resolvedCliPath || cliPath,
+    nodePath,
+  };
+}
+
+export function currentInstallationInfo(config) {
+  let cliPath = process.argv[1] || '';
+  try { if (cliPath && fs.existsSync(cliPath)) cliPath = fs.realpathSync(cliPath); } catch {}
+  return {
+    cliVersion:VERSION,
+    runtimeVersion:config?.runtime?.packageName ? packageVersionBesideCli(cliPath, config.runtime.packageName) : null,
+    cliPath:cliPath || null,
+    nodePath:process.execPath,
+  };
+}
+
+export function rememberCurrentInstallation(config, { service = false } = {}) {
+  if (!config || typeof config !== 'object') return config;
+  const info = currentInstallationInfo(config);
+  if (!info.cliPath || !info.nodePath) return config;
+  const key = info.nodePath + '\u0000' + info.cliPath;
+  const existing = Array.isArray(config.installations) ? config.installations.filter(item => item && typeof item === 'object') : [];
+  const filtered = existing.filter(item => ((item.nodePath || '') + '\u0000' + (item.cliPath || '')) !== key);
+  const record = {
+    nodePath:info.nodePath,
+    cliPath:info.cliPath,
+    cliVersion:info.cliVersion,
+    runtimeVersion:info.runtimeVersion,
+    service:Boolean(service),
+    lastSeenAt:new Date().toISOString(),
+  };
+  const installations = [...filtered, record].slice(-8);
+  const next = {
+    ...config,
+    installations,
+    ...(service ? { serviceInstalled:true, serviceCliPath:info.cliPath, serviceNodePath:info.nodePath } : {}),
+  };
+  saveConfig(next);
+  return next;
+}
+
+export function syncKnownInstallations(config, ...specs) {
+  const serviceInfo = serviceInstallationInfo(config);
+  const current = currentInstallationInfo(config);
+  const candidates = [
+    ...(Array.isArray(config?.installations) ? config.installations : []),
+    ...(serviceInfo.nodePath ? [{ nodePath:serviceInfo.nodePath, cliPath:serviceInfo.cliPath, service:true }] : []),
+  ];
+  const currentNode = (() => { try { return fs.realpathSync(current.nodePath); } catch { return current.nodePath; } })();
+  const seen = new Set();
+  const results = [];
+  for (const candidate of candidates) {
+    const nodePath = String(candidate?.nodePath || '').trim();
+    if (!nodePath || !fs.existsSync(nodePath)) continue;
+    let resolvedNode = nodePath;
+    try { resolvedNode = fs.realpathSync(nodePath); } catch {}
+    if (resolvedNode === currentNode || seen.has(resolvedNode)) continue;
+    seen.add(resolvedNode);
+    const required = Boolean(candidate?.service) || resolvedNode === serviceInfo.nodePath;
+    try {
+      npmGlobalInstallForNode(resolvedNode, ...specs);
+      results.push({ nodePath:resolvedNode, ok:true, required });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      results.push({ nodePath:resolvedNode, ok:false, required, error:message });
+      if (required) throw new Error('Could not update canonical ReMCP service installation at ' + resolvedNode + ': ' + message);
+    }
+  }
+  return results;
+}
+
 export function configurePostInstallAccess() {
   const platform = servicePlatform();
   try {
@@ -209,11 +400,13 @@ export function installPersistentAgent(config) {
   console.log(`Installing ReMCP ${VERSION}…`);
   npmGlobalInstall(`${PACKAGE_NAME}@${VERSION}`, config.runtime.packageSpec);
   const cliPath = globalCliPath();
-  if (platform === 'linux') installLinuxService(cliPath);
-  else if (platform === 'darwin') installMacService(cliPath);
+  const cliScript = resolvedCliScript(cliPath);
+  const nodePath = process.execPath;
+  if (platform === 'linux') installLinuxService(cliPath, nodePath);
+  else if (platform === 'darwin') installMacService(cliPath, { nodePath });
   else installWindowsService(cliPath);
   configurePostInstallAccess();
-  saveConfig({ ...config, serviceInstalled: true });
+  saveConfig({ ...config, serviceInstalled: true, serviceCliPath: cliScript, serviceNodePath: nodePath });
   console.log('ReMCP is installed as a background service. Future updates: remcp update');
 }
 
@@ -223,24 +416,24 @@ export function installPersistentAgent(config) {
 export function ensureServiceIfRecorded(config) {
   if (!persistentServiceExpected(config)) return false;
   try {
-    const cliPath = globalCliPath();
+    const cliPath = canonicalServiceCliPath(config);
+    const nodePath = canonicalServiceNodePath(config);
     const platform = servicePlatform();
     if (platform === 'linux') {
       if (!fs.existsSync(linuxServiceFile)) {
-        installLinuxService(cliPath);
+        installLinuxService(cliPath, nodePath);
       } else {
-        // Node managers can move the global npm prefix between updates (nvm -> Hermes was observed in
-        // production). An existing systemd unit then keeps launching the old CLI forever even though
-        // npm successfully installed the new one. Repair the launcher in place before restarting it.
+        // Keep the supervisor bound to the installation that owns the service. A manual update from
+        // another nvm/Hermes/Homebrew prefix must not silently steal service ownership.
+        const launcherFile = writeLinuxServiceLauncher(cliPath, nodePath);
         const unit = fs.readFileSync(linuxServiceFile, 'utf8');
-        const expected = `ExecStart=${quoteSystemd(cliPath)} start`;
+        const expected = `ExecStart=${quoteSystemd(launcherFile)} start --service`;
         if (!unit.includes(expected)) {
           const repaired = /^ExecStart=/m.test(unit) ? unit.replace(/^ExecStart=.*$/m, expected) : '';
           if (!repaired) {
-            // A unit that lost its ExecStart line (edited by hand, or written as `ExecStart = …`) cannot
-            // be patched by substitution. Rewriting the whole unit is what keeps the machine out of the
-            // "old CLI forever" loop, so fall back to a fresh install instead of giving up.
-            installLinuxService(cliPath);
+            // A hand-edited unit with no launcher line is replaced wholesale; the stable launcher is
+            // still refreshed first so the replacement never points back at a retired Node manager.
+            installLinuxService(cliPath, nodePath);
           } else {
             fs.writeFileSync(linuxServiceFile, repaired);
             run('systemctl', ['--user', 'daemon-reload']);
@@ -252,11 +445,14 @@ export function ensureServiceIfRecorded(config) {
       // boot out a loaded agent inline: this updater may itself be a descendant of that LaunchAgent.
       // installMacService either leaves an unchanged loaded job alone, bootstraps an unloaded job, or
       // hands a changed launcher to an independent transient launchd helper.
-      installMacService(cliPath, { restart: false });
+      installMacService(cliPath, { restart: false, nodePath });
     } else if (platform === 'win32') installWindowsService(cliPath);
     // Upgrade the legacy inferred state only after the supervisor repair succeeded. A failed repair
     // must not turn a stale artifact into a permanent "managed service" declaration.
-    if (config?.serviceInstalled !== true) saveConfig({ ...config, serviceInstalled: true });
+    const cliScript = resolvedCliScript(cliPath);
+    if (config?.serviceInstalled !== true || config?.serviceCliPath !== cliScript || config?.serviceNodePath !== nodePath) {
+      saveConfig({ ...config, serviceInstalled: true, serviceCliPath: cliScript, serviceNodePath: nodePath });
+    }
     return true;
   } catch (error) {
     console.error(`Could not ensure the background service: ${error instanceof Error ? error.message : String(error)}`);
@@ -281,7 +477,7 @@ export function restartPersistentServiceIfInstalled(config) {
     } else {
       // A plist can survive while launchd has no loaded job (older installs, logout/login cleanup,
       // manual bootout, or a failed previous update). Re-register it directly.
-      installMacService(globalCliPath());
+      installMacService(canonicalServiceCliPath(config), { nodePath:canonicalServiceNodePath(config) });
     }
     return macServiceLabel;
   }

package/src/cli/update.mjs

@@ -11,7 +11,7 @@ import { PACKAGE_NAME, VERSION } from '../version.mjs';
 import { loadConfig, saveConfig } from './config.mjs';
 import { installedVersion } from './doctor.mjs';
 import { linuxServiceFile, macServiceFile, officialOrigin } from './env.mjs';
-import { ensureServiceIfRecorded, npmGlobalInstall, restartPersistentServiceIfInstalled } from './service.mjs';
+import { currentInstallationInfo, ensureServiceIfRecorded, installationVersionsAtCliPath, npmGlobalInstall, persistentServiceExpected, rememberCurrentInstallation, restartPersistentServiceIfInstalled, serviceInstallationInfo, syncKnownInstallations } from './service.mjs';
 
 const UPDATE_DISCOVERY_TIMEOUT_MS = 5000;
 
@@ -168,19 +168,59 @@ export async function resolveUpdateTargets({
   }
 }
 
+export function updateAlreadyCurrent({ cfg, targets, currentInstall, serviceInstall, serviceExpected }) {
+  const targetClientVersion = specVersion(PACKAGE_NAME, targets?.clientSpec);
+  const targetRuntimeVersion = specVersion(cfg?.runtime?.packageName, targets?.runtimeSpec);
+  if (!targetClientVersion || !targetRuntimeVersion) return false;
+
+  const currentClientVersion = String(currentInstall?.cliVersion || '').trim();
+  const currentRuntimeVersion = String(currentInstall?.runtimeVersion || '').trim();
+  if (currentClientVersion !== targetClientVersion || currentRuntimeVersion !== targetRuntimeVersion) return false;
+
+  if (serviceExpected) {
+    if (String(serviceInstall?.cliVersion || '').trim() !== targetClientVersion) return false;
+    if (String(serviceInstall?.runtimeVersion || '').trim() !== targetRuntimeVersion) return false;
+  }
+
+  // A machine can have more than one Node manager. Do not claim "already current" while a known,
+  // still-existing ReMCP installation is recorded on an older release; the normal update path will
+  // converge it through syncKnownInstallations().
+  for (const item of Array.isArray(cfg?.installations) ? cfg.installations : []) {
+    const cliPath = String(item?.cliPath || '').trim();
+    if (!cliPath || !fs.existsSync(cliPath)) continue;
+    const actual = installationVersionsAtCliPath(cliPath, cfg.runtime.packageName);
+    if (String(actual.cliVersion || '').trim() !== targetClientVersion) return false;
+    if (String(actual.runtimeVersion || '').trim() !== targetRuntimeVersion) return false;
+  }
+  return true;
+}
+
 export async function updateCommand(flags) {
-  const cfg = loadConfig();
+  let cfg = rememberCurrentInstallation(loadConfig());
   const targets = await resolveUpdateTargets({ cfg, flags });
   if (targets.warning) console.error(`ReMCP update: ${targets.warning}`);
 
+  const currentInstall = currentInstallationInfo(cfg);
+  if (!currentInstall.runtimeVersion) currentInstall.runtimeVersion = installedVersion(cfg.runtime.packageName);
+  const serviceExpected = persistentServiceExpected(cfg);
+  const serviceInstall = serviceInstallationInfo(cfg);
+  const alreadyCurrent = targets.installable && updateAlreadyCurrent({
+    cfg,
+    targets,
+    currentInstall,
+    serviceInstall,
+    serviceExpected,
+  });
+
   if (flags.check) {
     console.log(JSON.stringify({
       current: VERSION,
-      installedRuntime: installedVersion(cfg.runtime.packageName),
+      installedRuntime: currentInstall.runtimeVersion,
       clientSpec: targets.clientSpec,
       runtimeSpec: targets.runtimeSpec,
       updateSource: targets.source,
       installable: targets.installable,
+      upToDate: alreadyCurrent,
       managedService: fs.existsSync(linuxServiceFile) || fs.existsSync(macServiceFile),
       supervisor: supervisorRestart() ?? 'none',
     }, null, 2));
@@ -191,14 +231,35 @@ export async function updateCommand(flags) {
     throw new Error(targets.warning || 'Could not resolve a complete client/runtime release pair.');
   }
 
+  if (alreadyCurrent) {
+    if (targets.persistRuntime) {
+      saveConfig({ ...cfg, runtime:{ ...cfg.runtime, packageSpec:targets.runtimeSpec } });
+    }
+    const currentRuntimeVersion = String(currentInstall.runtimeVersion || specVersion(cfg.runtime.packageName, targets.runtimeSpec) || '?');
+    console.log(`ReMCP is already up to date (client ${currentInstall.cliVersion || VERSION}, runtime ${currentRuntimeVersion}).`);
+    return;
+  }
+
   const before = { cli: VERSION, runtime: installedVersion(cfg.runtime.packageName) };
   console.log(`Updating ReMCP to ${targets.clientSpec} with ${targets.runtimeSpec}…`);
   npmGlobalInstall(targets.clientSpec, targets.runtimeSpec);
-  // The npm prefix can change across Node-manager upgrades. Repair an existing persistent-service
-  // launcher only after the install, when globalCliPath() points at the CLI we just installed.
+
+  // Converge every ReMCP installation this account has actually used on this machine. The canonical
+  // service installation is mandatory; secondary nvm/Hermes/Homebrew copies are best-effort and
+  // remain visible in status if they cannot be updated.
+  const synced = syncKnownInstallations(cfg, targets.clientSpec, targets.runtimeSpec);
+  for (const item of synced) {
+    if (!item.ok) console.error(`ReMCP update: could not sync secondary installation at ${item.nodePath}: ${item.error}`);
+  }
+
+  // Persist the validated runtime pair before repairing the supervisor so a repair cannot be
+  // overwritten by an older in-memory config object.
+  if (targets.persistRuntime) {
+    saveConfig({ ...cfg, runtime:{ ...cfg.runtime, packageSpec:targets.runtimeSpec } });
+    cfg = loadConfig();
+  }
   ensureServiceIfRecorded(cfg);
-  // Only a validated spec is persisted, so a failed update cannot leave the install unable to start.
-  if (targets.persistRuntime) saveConfig({ ...cfg, runtime: { ...cfg.runtime, packageSpec: targets.runtimeSpec } });
+  cfg = loadConfig();
   const after = { cli: installedVersion(PACKAGE_NAME), runtime: installedVersion(cfg.runtime.packageName) };
   const restarted = restartPersistentServiceIfInstalled(cfg);
   if (restarted) {

package/src/cli.mjs

@@ -2,15 +2,16 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { runAgent } from './agent.mjs';
+import { isNewer } from './agent-update.mjs';
 import { normalizeRuntime } from './runtime.mjs';
 import { PACKAGE_NAME, VERSION } from './version.mjs';
 import { probeFilesystemAccess } from './fs-access.mjs';
 
 import { ensureMachineId, loadConfig, readJsonFile, saveConfig, setTelemetry, telemetryState, writeJsonFile } from './cli/config.mjs';
 import { assertRuntimeTrust, pairWithDeviceCode } from './cli/connect.mjs';
-import { diagnoseLocalRuntime, runtimeAllowedRoots } from './cli/doctor.mjs';
+import { diagnoseLocalRuntime, installedVersion, runtimeAllowedRoots } from './cli/doctor.mjs';
 import { configFile, npm, officialOrigin, runtimeConfigFile } from './cli/env.mjs';
-import { installPersistentAgent, restartPersistentServiceIfInstalled, uninstallPersistentService } from './cli/service.mjs';
+import { currentInstallationInfo, installPersistentAgent, persistentServiceState, rememberCurrentInstallation, restartPersistentServiceIfInstalled, serviceInstallationInfo, uninstallPersistentService } from './cli/service.mjs';
 import { run } from './cli/shell.mjs';
 import { updateCommand } from './cli/update.mjs';
 function parse(argv) {
@@ -92,7 +93,15 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === 'start') {
-    const cfg = loadConfig();
+    const supervised = flags.service === true
+      || Boolean(process.env.INVOCATION_ID)
+      || String(process.env.XPC_SERVICE_NAME || '').includes('com.remcp.agent');
+    const cfg = rememberCurrentInstallation(loadConfig(), { service:supervised });
+    const service = persistentServiceState(cfg);
+    if (!supervised && service.active) {
+      console.log(`ReMCP is already running as a background service (${service.name}). Use \`remcp status\` to inspect it or \`remcp doctor\` to diagnose it.`);
+      return;
+    }
     const telemetry = telemetryState();
     await runAgent({
       ...cfg,
@@ -173,29 +182,97 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === 'status' || command === 'doctor') {
-    const cfg = loadConfig();
-    const health = await fetch(`${cfg.serverUrl}/health?fresh=${Date.now()}`, { cache: 'no-store' }).then(r => r.json()).catch(error => ({ error: error.message }));
+    const cfg = rememberCurrentInstallation(loadConfig());
+    const [health, advertised] = await Promise.all([
+      fetch(`${cfg.serverUrl}/health?fresh=${Date.now()}`, { cache:'no-store' })
+        .then(async response => ({ reachable:response.ok && (await response.json().catch(() => null))?.ok === true }))
+        .catch(error => ({ reachable:false, error:error.message })),
+      fetch(`${cfg.serverUrl}/api/agent/version?fresh=${Date.now()}`, { cache:'no-store' })
+        .then(response => response.ok ? response.json() : null)
+        .catch(() => null),
+    ]);
+    const telemetry = telemetryState();
+    const service = persistentServiceState(cfg);
+    const currentInstall = currentInstallationInfo(cfg);
+    const serviceInstall = serviceInstallationInfo(cfg);
+    const installedRuntime = installedVersion(cfg.runtime.packageName);
+    const targetClient = String(advertised?.cliVersion || '').trim() || null;
+    const targetRuntime = String(advertised?.runtime || '').trim() || null;
+    const configuredRuntime = String(cfg.runtime.packageSpec || '');
+    const installationPaths = new Set([
+      currentInstall.cliPath,
+      serviceInstall.cliPath,
+      ...(Array.isArray(cfg.installations) ? cfg.installations.map(item => item?.cliPath) : []),
+    ].filter(Boolean));
+    const multipleInstallations = installationPaths.size > 1;
+    const knownCliVersions = [VERSION, serviceInstall.cliVersion].filter(Boolean);
+    const knownRuntimeVersions = [installedRuntime, serviceInstall.runtimeVersion].filter(Boolean);
+    const versionConsistent = cfg.runtime.packageName === '@remcp/runtime'
+      ? new Set([...knownCliVersions, ...knownRuntimeVersions]).size <= 1
+      : new Set(knownCliVersions).size <= 1 && new Set(knownRuntimeVersions).size <= 1;
+    const clientMeetsTarget = Boolean(targetClient && !isNewer(targetClient, VERSION));
+    const configuredRuntimeMeetsTarget = Boolean(!targetRuntime || (configuredRuntime && !isNewer(targetRuntime, configuredRuntime)));
+    const runtimeMeetsTarget = Boolean(!targetRuntime || (installedRuntime && !isNewer(targetRuntime, installedRuntime)));
+    const serviceClientMeetsTarget = !service.installed
+      || Boolean(targetClient && serviceInstall.cliVersion && !isNewer(targetClient, serviceInstall.cliVersion));
+    const serviceRuntimeMeetsTarget = !service.installed
+      || Boolean(!targetRuntime || (serviceInstall.runtimeVersion && !isNewer(targetRuntime, serviceInstall.runtimeVersion)));
+    const upToDate = Boolean(
+      targetClient
+      && clientMeetsTarget
+      && configuredRuntimeMeetsTarget
+      && runtimeMeetsTarget
+      && serviceClientMeetsTarget
+      && serviceRuntimeMeetsTarget
+    );
+    const updateState = !targetClient
+      ? 'unknown'
+      : !upToDate
+        ? 'update_available'
+        : versionConsistent
+          ? (isNewer(VERSION, targetClient) ? 'ahead' : 'current')
+          : 'mixed_current';
     const report = {
-      configured: true,
-      cliVersion: VERSION,
-      deviceId: cfg.deviceId,
-      deviceName: cfg.deviceName,
-      server: cfg.serverUrl,
-      runtime: cfg.runtime,
-      telemetry: telemetryState(),
-      serverHealth: health,
+      configured:true,
+      device:{ id:cfg.deviceId, name:cfg.deviceName },
+      client:{ version:VERSION },
+      runtime:{
+        packageName:cfg.runtime.packageName,
+        configured:configuredRuntime,
+        installed:installedRuntime,
+      },
+      agent:{
+        mode:service.installed ? 'service' : 'manual',
+        running:service.active,
+        manager:service.manager,
+        serviceCliVersion:serviceInstall.cliVersion,
+        serviceRuntimeVersion:serviceInstall.runtimeVersion,
+      },
+      server:{
+        url:cfg.serverUrl,
+        reachable:health.reachable === true,
+        ...(health.error ? { error:health.error } : {}),
+      },
+      update:{
+        auto:cfg.autoUpdate !== false,
+        targetClient,
+        targetRuntime,
+        multipleInstallations,
+        versionConsistent,
+        state:updateState,
+        upToDate,
+      },
+      telemetry:{ enabled:telemetry.enabled },
     };
-    // `doctor` answers the question the workspace cannot: is this machine actually able to run a
-    // tool? It resolves the runtime entry, installs nothing, and tries one real MCP handshake with
-    // the runtime, so the failure is visible here instead of only as "runtime not running".
     if (command === 'doctor') {
       report.diagnosis = await diagnoseLocalRuntime(cfg);
-      // A computer can pass every other check and still be unable to write where the tools work:
-      // macOS answers EACCES for Desktop until TCC is granted, Windows has Controlled folder access,
-      // Linux answers EACCES for a folder this user does not own. The probe writes and removes a
-      // temporary file in each allowed root, so the doctor reports what actually happens rather than
-      // what the permission bits claim, and names the fix for this platform and this binary.
-      report.diagnosis.filesystem = await probeFilesystemAccess({ roots: runtimeAllowedRoots() });
+      report.diagnosis.filesystem = await probeFilesystemAccess({ roots:runtimeAllowedRoots() });
+      report.diagnostic = {
+        serviceExpected:service.expected,
+        serviceInstalled:service.installed,
+        runtimeEntry:cfg.runtime.entry,
+        npmManaged:true,
+      };
     }
     console.log(JSON.stringify(report, null, 2));
     if (command === 'doctor' && report.diagnosis.verdict !== 'ok') process.exitCode = 1;