@remcp/remcp 0.2.32 → 0.2.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/remcp",
-  "version": "0.2.32",
+  "version": "0.2.33",
   "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",
@@ -18,7 +18,7 @@
     "README.md"
   ],
   "scripts": {
-    "check": "node --check bin/remcp.mjs && node --check src/cli.mjs && node --check src/agent.mjs && node --check src/runtime.mjs && node --check src/version.mjs && node --check src/npm.mjs && node --check src/fs-access.mjs",
+    "check": "node --check bin/remcp.mjs && node --check src/agent.mjs && node --check src/cli.mjs && node --check src/cli/config.mjs && node --check src/cli/connect.mjs && node --check src/cli/doctor.mjs && node --check src/cli/env.mjs && node --check src/cli/service.mjs && node --check src/cli/shell.mjs && node --check src/fs-access.mjs && node --check src/npm.mjs && node --check src/runtime.mjs && node --check src/version.mjs",
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {

package/src/cli/config.mjs

@@ -0,0 +1,86 @@
+// The paired configuration and the two switches that live beside it: usage metrics and the machine id
+// the server uses to recognise this computer across pairings.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { normalizeRuntime } from '../runtime.mjs';
+
+import { configDir, configFile, machineIdFile, officialOrigin, runtimeConfigFile } from './env.mjs';
+
+export function loadConfig(required = true) {
+  if (!fs.existsSync(configFile)) {
+    if (!required) return undefined;
+    throw new Error(`ReMCP is not paired. Generate a pairing command at ${officialOrigin}/app/connect`);
+  }
+  const value = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  // A configuration that only carries preferences (for example after `remcp auto-update off`
+  // before pairing) has no runtime yet; it must not fail as if it were corrupt.
+  if (value.runtime !== undefined) value.runtime = normalizeRuntime(value.runtime);
+  return value;
+}
+
+export function saveConfig(value) {
+  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(configFile, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  fs.chmodSync(configFile, 0o600);
+}
+
+export function readJsonFile(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return {}; }
+}
+
+export function writeJsonFile(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+}
+
+export function flagEnabled(value) {
+  return value === undefined || value === null ? true : value !== false;
+}
+
+// One switch for the whole machine: the client and the runtime it spawns must agree,
+// otherwise the runtime would keep reporting after the user opted out.
+export function telemetryState() {
+  const client = readJsonFile(configFile);
+  const runtime = readJsonFile(runtimeConfigFile);
+  const clientEnabled = flagEnabled(client.telemetryEnabled);
+  const runtimeEnabled = flagEnabled(runtime.telemetryEnabled);
+  return {
+    enabled: clientEnabled && runtimeEnabled,
+    clientEnabled,
+    runtimeEnabled,
+    installReported: client.installReported === true,
+    configFile,
+    runtimeConfigFile,
+    transport: 'paired-agent-only',
+    endpoint: null,
+    collects: 'tool names, durations, outcomes, error classes, and device health samples',
+    neverCollects: 'file paths, file contents, command strings, tool arguments, and tool output',
+    thirdParty: false,
+    installPing: false,
+    remoteFeatureFlags: false,
+  };
+}
+
+export function setTelemetry(enabled) {
+  const client = readJsonFile(configFile);
+  client.telemetryEnabled = enabled;
+  writeJsonFile(configFile, client);
+  const runtime = readJsonFile(runtimeConfigFile);
+  runtime.telemetryEnabled = enabled;
+  writeJsonFile(runtimeConfigFile, runtime);
+  return telemetryState();
+}
+
+export function ensureMachineId() {
+  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  try {
+    const existing = fs.readFileSync(machineIdFile, 'utf8').trim();
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(existing)) return existing;
+  } catch {}
+  const value = randomUUID();
+  fs.writeFileSync(machineIdFile, value + '\n', { mode: 0o600 });
+  fs.chmodSync(machineIdFile, 0o600);
+  return value;
+}

package/src/cli/connect.mjs

@@ -0,0 +1,81 @@
+// Pairing a computer: the browser handshake a person approves, and the trust check that decides
+// whether a custom server may name the local runtime version.
+import os from 'node:os';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+
+import { ensureMachineId } from './config.mjs';
+import { officialOrigin } from './env.mjs';
+import { sleep } from './shell.mjs';
+
+// Opens the approval page in the person's browser. A machine that nobody is looking at only gets the
+// printed URL, so every failure here is silent and non-fatal.
+export function openInBrowser(url) {
+  try {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {}
+}
+
+// Device authorization (RFC 8628): the computer asks for a code, the person approves it in the
+// browser while signed in, and this process collects the credential by polling. The device never
+// sees a browser session or an account password.
+export async function pairWithDeviceCode(server, flags) {
+  const authorization = await fetch(`${server}/oauth/device_authorization`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      name: String(flags.name || os.hostname()),
+      hostname: os.hostname(),
+      platform: process.platform,
+      arch: process.arch,
+      machineId: ensureMachineId(),
+    }),
+  });
+  if (!authorization.ok) throw new Error(`Pairing failed (${authorization.status}): ${await authorization.text()}`);
+  const grant = await authorization.json();
+  const approvalUrl = grant.verification_uri_complete || grant.verification_uri;
+  console.log(`Approve this computer in your browser: ${approvalUrl}`);
+  console.log(`Pairing code: ${grant.user_code}  (expires in ${Math.max(1, Math.round(Number(grant.expires_in || 600) / 60))} minutes)`);
+  openInBrowser(approvalUrl);
+  console.log('Waiting for approval… (Ctrl+C to cancel)');
+  const deadline = Date.now() + (Number(grant.expires_in) || 600) * 1000;
+  let lastReminder = Date.now();
+  const intervalMs = Math.max(1, Number(grant.interval) || 5) * 1000;
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    const response = await fetch(`${server}/oauth/token`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        device_code: String(grant.device_code || ''),
+        machineId: ensureMachineId(),
+      }).toString(),
+    });
+    const data = await response.json().catch(() => ({}));
+    if (response.ok && data.device_token) return data;
+    if (data.error === 'authorization_pending' || data.error === 'slow_down') {
+      if (Date.now() - lastReminder > 60_000) {
+        lastReminder = Date.now();
+        const left = Math.max(0, Math.round((deadline - Date.now()) / 60_000));
+        console.log(`Still waiting — approve at ${approvalUrl} (about ${left} min left)`);
+      }
+      continue;
+    }
+    if (data.error === 'access_denied') throw new Error('That pairing request was denied in the browser. Run the command again if it was not you.');
+    if (data.error === 'expired_token') break;
+    throw new Error(`Pairing failed (${response.status}): ${JSON.stringify(data)}`);
+  }
+  throw new Error('The pairing code expired before it was approved. Run the command again.');
+}
+
+export function assertRuntimeTrust(server, flags) {
+  const origin = new URL(server).origin;
+  if (origin !== officialOrigin && !flags['trust-runtime']) {
+    throw new Error('Custom servers can provide local runtime metadata. Re-run with --trust-runtime only if you trust that server.');
+  }
+}

package/src/cli/doctor.mjs

@@ -0,0 +1,89 @@
+// What remcp doctor answers: whether this machine can really run a tool, and where the runtime is
+// allowed to write. The checks install nothing and report the exact failing step.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { localRuntimeEntry } from '../agent.mjs';
+import { npmVersion, resolveNpm } from '../npm.mjs';
+import { PACKAGE_NAME, VERSION } from '../version.mjs';
+
+import { npm, runtimeConfigFile } from './env.mjs';
+
+// when it really owns this process: a terminal gets an explicit instruction instead of a silent exit
+// that would take the device offline.
+// One real handshake with the local runtime, plus everything needed to explain a failure: where the
+// entry resolved, whether the package is installed, the node that would run it, and the exact error.
+export async function diagnoseLocalRuntime(cfg) {
+  const packageName = cfg.runtime?.packageName || '';
+  const diagnosis = {
+    platform: `${process.platform} ${process.arch}`,
+    node: process.execPath,
+    nodeVersion: process.versions.node,
+    packageName,
+    packageSpec: cfg.runtime?.packageSpec || '',
+    installedRuntime: installedVersion(packageName),
+    installedClient: installedVersion(PACKAGE_NAME),
+  };
+  const resolved = resolveNpm();
+  const npmInfo = npmVersion(resolved);
+  diagnosis.npm = npmInfo ? { version: npmInfo.version, source: npmInfo.source } : { error: `npm could not be executed (tried ${resolved.source})` };
+  let entry = '';
+  try {
+    entry = localRuntimeEntry(cfg.runtime);
+    diagnosis.entry = entry;
+    diagnosis.entryExists = fs.existsSync(entry);
+  } catch (error) {
+    diagnosis.entry = null;
+    diagnosis.entryExists = false;
+    diagnosis.verdict = 'runtime-not-installed';
+    diagnosis.error = error instanceof Error ? error.message : String(error);
+    diagnosis.hint = `Reinstall with: npx --yes ${PACKAGE_NAME}@latest update`;
+    return diagnosis;
+  }
+  if (!diagnosis.entryExists) {
+    diagnosis.verdict = 'runtime-entry-missing';
+    diagnosis.hint = `Reinstall with: npx --yes ${PACKAGE_NAME}@latest update`;
+    return diagnosis;
+  }
+  try {
+    const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
+    const { StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js');
+    const client = new Client({ name: 'remcp-doctor', version: VERSION });
+    const stdio = new StdioClientTransport({ command: process.execPath, args: [entry], env: { ...process.env }, maxBufferSize: 4 * 1024 * 1024 });
+    const stderr = [];
+    stdio.onerror = error => stderr.push(String(error?.message || error));
+    await client.connect(stdio);
+    diagnosis.runtimeVersion = client.getServerVersion()?.version || 'unknown';
+    const tools = await client.listTools(undefined, { timeout: 20000 });
+    diagnosis.tools = tools.tools.length;
+    diagnosis.verdict = 'ok';
+    await client.close();
+    return diagnosis;
+  } catch (error) {
+    diagnosis.verdict = 'runtime-handshake-failed';
+    diagnosis.error = error instanceof Error ? error.message : String(error);
+    diagnosis.hint = 'Run the entry above by hand to see its output, then reinstall with: npx --yes @remcp/remcp@latest update';
+    return diagnosis;
+  }
+}
+
+// Reads the version a freshly installed global package reports, so an update that installed
+// nothing (wrong prefix, npm cache, permissions) is reported instead of assumed successful.
+// The roots the runtime is allowed to work in, as the person configured them. An empty list means
+// "the whole file system", so the doctor probes the home directory instead of guessing a root.
+export function runtimeAllowedRoots() {
+  try {
+    const configured = JSON.parse(fs.readFileSync(runtimeConfigFile, 'utf8')).allowedRoots;
+    if (Array.isArray(configured) && configured.length) return configured.map(root => String(root).replace(/^~/, os.homedir()));
+  } catch {}
+  return [os.homedir()];
+}
+
+export function installedVersion(packageName) {
+  const prefix = spawnSync(npm.command, [...npm.args, 'prefix', '--global'], { encoding: 'utf8' });
+  if (prefix.error || prefix.status !== 0) return null;
+  const manifest = path.join(String(prefix.stdout || '').trim(), 'lib', 'node_modules', ...packageName.split('/'), 'package.json');
+  try { return JSON.parse(fs.readFileSync(manifest, 'utf8')).version || null; } catch { return null; }
+}

package/src/cli/env.mjs

@@ -0,0 +1,21 @@
+// Where the CLI keeps its state and which npm it drives. Everything here is resolved once, at import
+// time, so a background service and an interactive shell agree on the same paths.
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveNpm } from '../npm.mjs';
+
+export const home = os.homedir();
+export const configDir = process.env.REMCP_CONFIG_DIR || path.join(home, '.config', 'remcp');
+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 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');
+export const windowsTaskName = 'ReMCP Agent';
+// How npm is invoked is resolved from the running node when possible: a background service has a
+// minimal PATH, which is why auto-update used to find no npm on macOS. See src/npm.mjs.
+export const npm = resolveNpm();
+export const officialOrigin = 'https://remcp.site';

package/src/cli/service.mjs

@@ -0,0 +1,214 @@
+// Installing, repairing and removing the background agent: one supervisor per platform, plus the
+// write-access tweaks a fresh install needs. Nothing here is reachable from a model or an MCP tool.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { PACKAGE_NAME, VERSION } from '../version.mjs';
+
+import { saveConfig } from './config.mjs';
+import { home, linuxServiceFile, macLogFile, macServiceFile, macServiceLabel, npm, windowsTaskName } from './env.mjs';
+import { output, run } from './shell.mjs';
+
+export function servicePlatform() {
+  return process.env.NODE_ENV === 'test' && process.env.REMCP_TEST_PLATFORM ? process.env.REMCP_TEST_PLATFORM : process.platform;
+}
+
+export function globalPrefix() {
+  return output(npm.command, [...npm.args, 'prefix', '--global']);
+}
+
+export function globalCliPath() {
+  const prefix = globalPrefix();
+  return servicePlatform() === 'win32' ? path.join(prefix, 'remcp.cmd') : path.join(prefix, 'bin', 'remcp');
+}
+
+export function npmGlobalInstall(...specs) {
+  run(npm.command, [...npm.args, 'install', '--global', ...specs, '--no-audit', '--no-fund', '--loglevel=error']);
+}
+
+export function quoteSystemd(value) {
+  return `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+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`;
+  fs.mkdirSync(path.dirname(linuxServiceFile), { recursive: true });
+  fs.writeFileSync(linuxServiceFile, unit);
+  run('systemctl', ['--user', 'daemon-reload']);
+  run('systemctl', ['--user', 'enable', '--now', 'remcp-agent.service']);
+}
+
+export function macLaunchDomain() {
+  if (typeof process.getuid !== 'function') throw new Error('Could not determine the current macOS user');
+  return `gui/${process.getuid()}`;
+}
+
+export function installMacService(cliPath = globalCliPath()) {
+  const domain = macLaunchDomain();
+  const target = `${domain}/${macServiceLabel}`;
+  // 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);
+  fs.mkdirSync(path.dirname(macServiceFile), { recursive: true });
+  fs.mkdirSync(path.dirname(macLogFile), { recursive: true });
+  const plist = `<?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`;
+  fs.writeFileSync(macServiceFile, plist, { mode: 0o600 });
+  spawnSync('launchctl', ['bootout', domain, macServiceFile], { stdio: 'ignore' });
+  run('launchctl', ['bootstrap', domain, macServiceFile]);
+  run('launchctl', ['enable', target]);
+  run('launchctl', ['kickstart', '-k', target]);
+}
+
+export function installWindowsService(cliPath = globalCliPath()) {
+  const command = `"${cliPath}" start`;
+  run('schtasks.exe', ['/Create', '/TN', windowsTaskName, '/TR', command, '/SC', 'ONLOGON', '/RL', 'HIGHEST', '/F']);
+  run('schtasks.exe', ['/Run', '/TN', windowsTaskName]);
+}
+
+export function configurePostInstallAccess() {
+  const platform = servicePlatform();
+  try {
+    if (platform === 'darwin') configureMacWriteAccess();
+    else if (platform === 'win32') configureWindowsWriteAccess();
+    else configureLinuxWriteAccess();
+  } catch (error) {
+    console.error(`Could not configure write access: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function configureMacWriteAccess() {
+  const appName = path.basename(process.execPath);
+  const terminalApp = path.basename(process.env.SHELL || '/bin/zsh');
+  const workspaceDir = path.join(home, 'Library', 'Application Support', 'ReMCP');
+  try { fs.mkdirSync(workspaceDir, { recursive: true }); } catch {}
+  try { run('chmod', ['-R', '755', workspaceDir]); } catch {}
+  try {
+    const script = `tell application "System Preferences" to activate\ndelay 1\ntell application "System Events" to click UI element "Privacy" of toolbar 1 of window "Security & Privacy" of process "System Preferences"\ndelay 1\ntell application "System Events" to click row 4 of table 1 of scroll area 1 of window "Privacy" of application process "System Preferences"\ndelay 1\n`;
+    spawnSync('osascript', ['-e', script], { stdio: 'ignore' });
+  } catch {}
+  console.log('Note: For full Desktop/Documents access on macOS, go to System Settings → Privacy & Security → Full Disk Access and add ReMCP or your Terminal app.');
+}
+
+export function configureWindowsWriteAccess() {
+  try { run('schtasks.exe', ['/Change', '/TN', windowsTaskName, '/RL', 'HIGHEST', '/IT']); } catch {}
+  try {
+    const workspaceDir = path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'ReMCP');
+    fs.mkdirSync(workspaceDir, { recursive: true });
+  } catch {}
+  console.log('ReMCP configured with elevated privileges for full write access.');
+}
+
+export function configureLinuxWriteAccess() {
+  const dirs = [path.join(home, 'Desktop'), path.join(home, 'Documents'), path.join(home, 'Downloads')];
+  for (const dir of dirs) {
+    try {
+      if (fs.existsSync(dir)) run('chown', [`${os.userInfo().username}:${os.userInfo().gid}`, dir]);
+    } catch {}
+  }
+  try {
+    const workspaceDir = path.join(home, '.local', 'share', 'ReMCP');
+    fs.mkdirSync(workspaceDir, { recursive: true });
+  } catch {}
+}
+
+export function installPersistentAgent(config) {
+  const platform = servicePlatform();
+  if (!['linux', 'darwin', 'win32'].includes(platform)) throw new Error(`Automatic background service installation is not supported on ${platform}`);
+  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);
+  else installWindowsService(cliPath);
+  configurePostInstallAccess();
+  saveConfig({ ...config, serviceInstalled: true });
+  console.log('ReMCP is installed as a background service. Future updates: remcp update');
+}
+
+// A machine that was installed as a service must still be one after an update: if the job is missing
+// (a failed install, a cleaned LaunchAgents directory, a re-imaged user), the next update recreates
+// it instead of leaving a hand-over to a process nobody supervises.
+export function ensureServiceIfRecorded(config) {
+  if (config?.serviceInstalled !== true) return false;
+  try {
+    const cliPath = globalCliPath();
+    const platform = servicePlatform();
+    if (platform === 'linux') {
+      if (!fs.existsSync(linuxServiceFile)) {
+        installLinuxService(cliPath);
+      } 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.
+        const unit = fs.readFileSync(linuxServiceFile, 'utf8');
+        const expected = `ExecStart=${quoteSystemd(cliPath)} start`;
+        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);
+          } else {
+            fs.writeFileSync(linuxServiceFile, repaired);
+            run('systemctl', ['--user', 'daemon-reload']);
+          }
+        }
+      }
+    } else if (platform === 'darwin') {
+      // launchd bakes the interpreter and the CLI path into the plist, so a Node manager that moves
+      // its global prefix leaves the agent launching a file that no longer exists — the same loop the
+      // Linux unit above is repaired for. Reinstalling is idempotent (bootout, bootstrap, enable,
+      // kickstart) and is what the Windows task already does on every update.
+      installMacService(cliPath);
+    } else if (platform === 'win32') installWindowsService(cliPath);
+    return true;
+  } catch (error) {
+    console.error(`Could not ensure the background service: ${error instanceof Error ? error.message : String(error)}`);
+    return false;
+  }
+}
+
+export function restartPersistentServiceIfInstalled() {
+  const platform = servicePlatform();
+  if (platform === 'linux' && fs.existsSync(linuxServiceFile)) {
+    run('systemctl', ['--user', 'daemon-reload']);
+    run('systemctl', ['--user', 'restart', 'remcp-agent.service']);
+    return 'remcp-agent.service';
+  }
+  if (platform === 'darwin' && fs.existsSync(macServiceFile)) {
+    run('launchctl', ['kickstart', '-k', `${macLaunchDomain()}/${macServiceLabel}`]);
+    return macServiceLabel;
+  }
+  if (platform === 'win32') {
+    const result = spawnSync('schtasks.exe', ['/Query', '/TN', windowsTaskName], { stdio: 'ignore' });
+    if (result.status === 0) {
+      run('schtasks.exe', ['/Run', '/TN', windowsTaskName]);
+      return windowsTaskName;
+    }
+  }
+  return null;
+}
+
+export function uninstallPersistentService() {
+  const platform = servicePlatform();
+  if (platform === 'linux') {
+    spawnSync('systemctl', ['--user', 'disable', '--now', 'remcp-agent.service'], { stdio: 'inherit' });
+    try { fs.unlinkSync(linuxServiceFile); } catch {}
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'inherit' });
+  } else if (platform === 'darwin') {
+    const domain = macLaunchDomain();
+    spawnSync('launchctl', ['bootout', domain, macServiceFile], { stdio: 'ignore' });
+    try { fs.unlinkSync(macServiceFile); } catch {}
+  } else if (platform === 'win32') {
+    spawnSync('schtasks.exe', ['/End', '/TN', windowsTaskName], { stdio: 'ignore' });
+    spawnSync('schtasks.exe', ['/Delete', '/TN', windowsTaskName, '/F'], { stdio: 'ignore' });
+  }
+}

package/src/cli/shell.mjs

@@ -0,0 +1,20 @@
+// The two ways this CLI runs another program: streaming straight to the terminal, or captured for a
+// value it has to read back. Sleep lives here so pairing can wait without its own timer.
+import { spawnSync } from 'node:child_process';
+
+export function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { stdio: 'inherit', ...options });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} failed with exit code ${result.status}`);
+  return result;
+}
+
+export function output(command, args) {
+  const result = spawnSync(command, args, { encoding: 'utf8' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} failed with exit code ${result.status}`);
+  return String(result.stdout || '').trim();
+}
+
+export const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+

package/src/cli.mjs

@@ -2,29 +2,17 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
-import { spawn, spawnSync } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
-import { localRuntimeEntry, runAgent, supervisorRestart } from './agent.mjs';
-import { npmVersion, resolveNpm } from './npm.mjs';
+import { runAgent, supervisorRestart } from './agent.mjs';
 import { isRuntimeSpecFor, normalizeRuntime } from './runtime.mjs';
 import { PACKAGE_NAME, VERSION } from './version.mjs';
 import { probeFilesystemAccess } from './fs-access.mjs';
 
-const home = os.homedir();
-const configDir = process.env.REMCP_CONFIG_DIR || path.join(home, '.config', 'remcp');
-const configFile = path.join(configDir, 'config.json');
-const runtimeConfigFile = path.join(configDir, 'runtime.json');
-const machineIdFile = path.join(configDir, 'machine-id');
-const linuxServiceFile = path.join(home, '.config', 'systemd', 'user', 'remcp-agent.service');
-const macServiceLabel = 'com.remcp.agent';
-const macServiceFile = path.join(home, 'Library', 'LaunchAgents', `${macServiceLabel}.plist`);
-const macLogFile = path.join(home, 'Library', 'Logs', 'remcp-agent.log');
-const windowsTaskName = 'ReMCP Agent';
-// How npm is invoked is resolved from the running node when possible: a background service has a
-// minimal PATH, which is why auto-update used to find no npm on macOS. See src/npm.mjs.
-const npm = resolveNpm();
-const officialOrigin = 'https://remcp.site';
-
+import { ensureMachineId, loadConfig, readJsonFile, saveConfig, setTelemetry, telemetryState, writeJsonFile } from './cli/config.mjs';
+import { assertRuntimeTrust, pairWithDeviceCode } from './cli/connect.mjs';
+import { diagnoseLocalRuntime, installedVersion, runtimeAllowedRoots } from './cli/doctor.mjs';
+import { configFile, linuxServiceFile, macServiceFile, npm, officialOrigin, runtimeConfigFile } from './cli/env.mjs';
+import { ensureServiceIfRecorded, globalCliPath, installPersistentAgent, npmGlobalInstall, restartPersistentServiceIfInstalled, uninstallPersistentService } from './cli/service.mjs';
+import { run } from './cli/shell.mjs';
 function parse(argv) {
   const [command = 'help', ...rest] = argv;
   const flags = {};
@@ -37,455 +25,6 @@ function parse(argv) {
   return { command, flags, positional };
 }
 
-function run(command, args, options = {}) {
-  const result = spawnSync(command, args, { stdio: 'inherit', ...options });
-  if (result.error) throw result.error;
-  if (result.status !== 0) throw new Error(`${command} failed with exit code ${result.status}`);
-  return result;
-}
-
-function output(command, args) {
-  const result = spawnSync(command, args, { encoding: 'utf8' });
-  if (result.error) throw result.error;
-  if (result.status !== 0) throw new Error(`${command} failed with exit code ${result.status}`);
-  return String(result.stdout || '').trim();
-}
-
-function loadConfig(required = true) {
-  if (!fs.existsSync(configFile)) {
-    if (!required) return undefined;
-    throw new Error(`ReMCP is not paired. Generate a pairing command at ${officialOrigin}/app/connect`);
-  }
-  const value = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-  // A configuration that only carries preferences (for example after `remcp auto-update off`
-  // before pairing) has no runtime yet; it must not fail as if it were corrupt.
-  if (value.runtime !== undefined) value.runtime = normalizeRuntime(value.runtime);
-  return value;
-}
-
-function saveConfig(value) {
-  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
-  fs.writeFileSync(configFile, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
-  fs.chmodSync(configFile, 0o600);
-}
-
-function readJsonFile(file) {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return {}; }
-}
-
-function writeJsonFile(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
-  fs.chmodSync(file, 0o600);
-}
-
-function flagEnabled(value) {
-  return value === undefined || value === null ? true : value !== false;
-}
-
-// One switch for the whole machine: the client and the runtime it spawns must agree,
-// otherwise the runtime would keep reporting after the user opted out.
-function telemetryState() {
-  const client = readJsonFile(configFile);
-  const runtime = readJsonFile(runtimeConfigFile);
-  const clientEnabled = flagEnabled(client.telemetryEnabled);
-  const runtimeEnabled = flagEnabled(runtime.telemetryEnabled);
-  return {
-    enabled: clientEnabled && runtimeEnabled,
-    clientEnabled,
-    runtimeEnabled,
-    installReported: client.installReported === true,
-    configFile,
-    runtimeConfigFile,
-    transport: 'paired-agent-only',
-    endpoint: null,
-    collects: 'tool names, durations, outcomes, error classes, and device health samples',
-    neverCollects: 'file paths, file contents, command strings, tool arguments, and tool output',
-    thirdParty: false,
-    installPing: false,
-    remoteFeatureFlags: false,
-  };
-}
-
-function setTelemetry(enabled) {
-  const client = readJsonFile(configFile);
-  client.telemetryEnabled = enabled;
-  writeJsonFile(configFile, client);
-  const runtime = readJsonFile(runtimeConfigFile);
-  runtime.telemetryEnabled = enabled;
-  writeJsonFile(runtimeConfigFile, runtime);
-  return telemetryState();
-}
-
-function ensureMachineId() {
-  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
-  try {
-    const existing = fs.readFileSync(machineIdFile, 'utf8').trim();
-    if (/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(existing)) return existing;
-  } catch {}
-  const value = randomUUID();
-  fs.writeFileSync(machineIdFile, value + '\n', { mode: 0o600 });
-  fs.chmodSync(machineIdFile, 0o600);
-  return value;
-}
-
-function servicePlatform() {
-  return process.env.NODE_ENV === 'test' && process.env.REMCP_TEST_PLATFORM ? process.env.REMCP_TEST_PLATFORM : process.platform;
-}
-
-function globalPrefix() {
-  return output(npm.command, [...npm.args, 'prefix', '--global']);
-}
-
-function globalCliPath() {
-  const prefix = globalPrefix();
-  return servicePlatform() === 'win32' ? path.join(prefix, 'remcp.cmd') : path.join(prefix, 'bin', 'remcp');
-}
-
-function npmGlobalInstall(...specs) {
-  run(npm.command, [...npm.args, 'install', '--global', ...specs, '--no-audit', '--no-fund', '--loglevel=error']);
-}
-
-function quoteSystemd(value) {
-  return `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
-}
-
-function xmlEscape(value) {
-  return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
-}
-
-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`;
-  fs.mkdirSync(path.dirname(linuxServiceFile), { recursive: true });
-  fs.writeFileSync(linuxServiceFile, unit);
-  run('systemctl', ['--user', 'daemon-reload']);
-  run('systemctl', ['--user', 'enable', '--now', 'remcp-agent.service']);
-}
-
-function macLaunchDomain() {
-  if (typeof process.getuid !== 'function') throw new Error('Could not determine the current macOS user');
-  return `gui/${process.getuid()}`;
-}
-
-function installMacService(cliPath = globalCliPath()) {
-  const domain = macLaunchDomain();
-  const target = `${domain}/${macServiceLabel}`;
-  // 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);
-  fs.mkdirSync(path.dirname(macServiceFile), { recursive: true });
-  fs.mkdirSync(path.dirname(macLogFile), { recursive: true });
-  const plist = `<?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`;
-  fs.writeFileSync(macServiceFile, plist, { mode: 0o600 });
-  spawnSync('launchctl', ['bootout', domain, macServiceFile], { stdio: 'ignore' });
-  run('launchctl', ['bootstrap', domain, macServiceFile]);
-  run('launchctl', ['enable', target]);
-  run('launchctl', ['kickstart', '-k', target]);
-}
-
-function installWindowsService(cliPath = globalCliPath()) {
-  const command = `"${cliPath}" start`;
-  run('schtasks.exe', ['/Create', '/TN', windowsTaskName, '/TR', command, '/SC', 'ONLOGON', '/RL', 'HIGHEST', '/F']);
-  run('schtasks.exe', ['/Run', '/TN', windowsTaskName]);
-}
-
-function configurePostInstallAccess() {
-  const platform = servicePlatform();
-  try {
-    if (platform === 'darwin') configureMacWriteAccess();
-    else if (platform === 'win32') configureWindowsWriteAccess();
-    else configureLinuxWriteAccess();
-  } catch (error) {
-    console.error(`Could not configure write access: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-
-function configureMacWriteAccess() {
-  const appName = path.basename(process.execPath);
-  const terminalApp = path.basename(process.env.SHELL || '/bin/zsh');
-  const workspaceDir = path.join(home, 'Library', 'Application Support', 'ReMCP');
-  try { fs.mkdirSync(workspaceDir, { recursive: true }); } catch {}
-  try { run('chmod', ['-R', '755', workspaceDir]); } catch {}
-  try {
-    const script = `tell application "System Preferences" to activate\ndelay 1\ntell application "System Events" to click UI element "Privacy" of toolbar 1 of window "Security & Privacy" of process "System Preferences"\ndelay 1\ntell application "System Events" to click row 4 of table 1 of scroll area 1 of window "Privacy" of application process "System Preferences"\ndelay 1\n`;
-    spawnSync('osascript', ['-e', script], { stdio: 'ignore' });
-  } catch {}
-  console.log('Note: For full Desktop/Documents access on macOS, go to System Settings → Privacy & Security → Full Disk Access and add ReMCP or your Terminal app.');
-}
-
-function configureWindowsWriteAccess() {
-  try { run('schtasks.exe', ['/Change', '/TN', windowsTaskName, '/RL', 'HIGHEST', '/IT']); } catch {}
-  try {
-    const workspaceDir = path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'ReMCP');
-    fs.mkdirSync(workspaceDir, { recursive: true });
-  } catch {}
-  console.log('ReMCP configured with elevated privileges for full write access.');
-}
-
-function configureLinuxWriteAccess() {
-  const dirs = [path.join(home, 'Desktop'), path.join(home, 'Documents'), path.join(home, 'Downloads')];
-  for (const dir of dirs) {
-    try {
-      if (fs.existsSync(dir)) run('chown', [`${os.userInfo().username}:${os.userInfo().gid}`, dir]);
-    } catch {}
-  }
-  try {
-    const workspaceDir = path.join(home, '.local', 'share', 'ReMCP');
-    fs.mkdirSync(workspaceDir, { recursive: true });
-  } catch {}
-}
-
-function installPersistentAgent(config) {
-  const platform = servicePlatform();
-  if (!['linux', 'darwin', 'win32'].includes(platform)) throw new Error(`Automatic background service installation is not supported on ${platform}`);
-  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);
-  else installWindowsService(cliPath);
-  configurePostInstallAccess();
-  saveConfig({ ...config, serviceInstalled: true });
-  console.log('ReMCP is installed as a background service. Future updates: remcp update');
-}
-
-// A machine that was installed as a service must still be one after an update: if the job is missing
-// (a failed install, a cleaned LaunchAgents directory, a re-imaged user), the next update recreates
-// it instead of leaving a hand-over to a process nobody supervises.
-function ensureServiceIfRecorded(config) {
-  if (config?.serviceInstalled !== true) return false;
-  try {
-    const cliPath = globalCliPath();
-    const platform = servicePlatform();
-    if (platform === 'linux') {
-      if (!fs.existsSync(linuxServiceFile)) {
-        installLinuxService(cliPath);
-      } 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.
-        const unit = fs.readFileSync(linuxServiceFile, 'utf8');
-        const expected = `ExecStart=${quoteSystemd(cliPath)} start`;
-        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);
-          } else {
-            fs.writeFileSync(linuxServiceFile, repaired);
-            run('systemctl', ['--user', 'daemon-reload']);
-          }
-        }
-      }
-    } else if (platform === 'darwin') {
-      // launchd bakes the interpreter and the CLI path into the plist, so a Node manager that moves
-      // its global prefix leaves the agent launching a file that no longer exists — the same loop the
-      // Linux unit above is repaired for. Reinstalling is idempotent (bootout, bootstrap, enable,
-      // kickstart) and is what the Windows task already does on every update.
-      installMacService(cliPath);
-    } else if (platform === 'win32') installWindowsService(cliPath);
-    return true;
-  } catch (error) {
-    console.error(`Could not ensure the background service: ${error instanceof Error ? error.message : String(error)}`);
-    return false;
-  }
-}
-
-// Opens the approval page in the person's browser. A machine that nobody is looking at only gets the
-// printed URL, so every failure here is silent and non-fatal.
-function openInBrowser(url) {
-  try {
-    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
-    const child = spawn(command, args, { stdio: 'ignore', detached: true });
-    child.on('error', () => {});
-    child.unref();
-  } catch {}
-}
-
-const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
-
-// Device authorization (RFC 8628): the computer asks for a code, the person approves it in the
-// browser while signed in, and this process collects the credential by polling. The device never
-// sees a browser session or an account password.
-async function pairWithDeviceCode(server, flags) {
-  const authorization = await fetch(`${server}/oauth/device_authorization`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({
-      name: String(flags.name || os.hostname()),
-      hostname: os.hostname(),
-      platform: process.platform,
-      arch: process.arch,
-      machineId: ensureMachineId(),
-    }),
-  });
-  if (!authorization.ok) throw new Error(`Pairing failed (${authorization.status}): ${await authorization.text()}`);
-  const grant = await authorization.json();
-  const approvalUrl = grant.verification_uri_complete || grant.verification_uri;
-  console.log(`Approve this computer in your browser: ${approvalUrl}`);
-  console.log(`Pairing code: ${grant.user_code}  (expires in ${Math.max(1, Math.round(Number(grant.expires_in || 600) / 60))} minutes)`);
-  openInBrowser(approvalUrl);
-  console.log('Waiting for approval… (Ctrl+C to cancel)');
-  const deadline = Date.now() + (Number(grant.expires_in) || 600) * 1000;
-  let lastReminder = Date.now();
-  const intervalMs = Math.max(1, Number(grant.interval) || 5) * 1000;
-  while (Date.now() < deadline) {
-    await sleep(intervalMs);
-    const response = await fetch(`${server}/oauth/token`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body: new URLSearchParams({
-        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-        device_code: String(grant.device_code || ''),
-        machineId: ensureMachineId(),
-      }).toString(),
-    });
-    const data = await response.json().catch(() => ({}));
-    if (response.ok && data.device_token) return data;
-    if (data.error === 'authorization_pending' || data.error === 'slow_down') {
-      if (Date.now() - lastReminder > 60_000) {
-        lastReminder = Date.now();
-        const left = Math.max(0, Math.round((deadline - Date.now()) / 60_000));
-        console.log(`Still waiting — approve at ${approvalUrl} (about ${left} min left)`);
-      }
-      continue;
-    }
-    if (data.error === 'access_denied') throw new Error('That pairing request was denied in the browser. Run the command again if it was not you.');
-    if (data.error === 'expired_token') break;
-    throw new Error(`Pairing failed (${response.status}): ${JSON.stringify(data)}`);
-  }
-  throw new Error('The pairing code expired before it was approved. Run the command again.');
-}
-
-function restartPersistentServiceIfInstalled() {
-  const platform = servicePlatform();
-  if (platform === 'linux' && fs.existsSync(linuxServiceFile)) {
-    run('systemctl', ['--user', 'daemon-reload']);
-    run('systemctl', ['--user', 'restart', 'remcp-agent.service']);
-    return 'remcp-agent.service';
-  }
-  if (platform === 'darwin' && fs.existsSync(macServiceFile)) {
-    run('launchctl', ['kickstart', '-k', `${macLaunchDomain()}/${macServiceLabel}`]);
-    return macServiceLabel;
-  }
-  if (platform === 'win32') {
-    const result = spawnSync('schtasks.exe', ['/Query', '/TN', windowsTaskName], { stdio: 'ignore' });
-    if (result.status === 0) {
-      run('schtasks.exe', ['/Run', '/TN', windowsTaskName]);
-      return windowsTaskName;
-    }
-  }
-  return null;
-}
-
-// The agent the user installed with `remcp install` is the one this CLI manages. A machine can also
-// be supervised by its own systemd unit, by Docker, or by a terminal, and in those cases installing
-// a new version is not enough: the running process keeps the old code until something restarts it.
-// `supervisorRestart` (agent.mjs) answers which of those is true, and only reports a service manager
-// when it really owns this process: a terminal gets an explicit instruction instead of a silent exit
-// that would take the device offline.
-// One real handshake with the local runtime, plus everything needed to explain a failure: where the
-// entry resolved, whether the package is installed, the node that would run it, and the exact error.
-async function diagnoseLocalRuntime(cfg) {
-  const packageName = cfg.runtime?.packageName || '';
-  const diagnosis = {
-    platform: `${process.platform} ${process.arch}`,
-    node: process.execPath,
-    nodeVersion: process.versions.node,
-    packageName,
-    packageSpec: cfg.runtime?.packageSpec || '',
-    installedRuntime: installedVersion(packageName),
-    installedClient: installedVersion(PACKAGE_NAME),
-  };
-  const resolved = resolveNpm();
-  const npmInfo = npmVersion(resolved);
-  diagnosis.npm = npmInfo ? { version: npmInfo.version, source: npmInfo.source } : { error: `npm could not be executed (tried ${resolved.source})` };
-  let entry = '';
-  try {
-    entry = localRuntimeEntry(cfg.runtime);
-    diagnosis.entry = entry;
-    diagnosis.entryExists = fs.existsSync(entry);
-  } catch (error) {
-    diagnosis.entry = null;
-    diagnosis.entryExists = false;
-    diagnosis.verdict = 'runtime-not-installed';
-    diagnosis.error = error instanceof Error ? error.message : String(error);
-    diagnosis.hint = `Reinstall with: npx --yes ${PACKAGE_NAME}@latest update`;
-    return diagnosis;
-  }
-  if (!diagnosis.entryExists) {
-    diagnosis.verdict = 'runtime-entry-missing';
-    diagnosis.hint = `Reinstall with: npx --yes ${PACKAGE_NAME}@latest update`;
-    return diagnosis;
-  }
-  try {
-    const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
-    const { StdioClientTransport } = await import('@modelcontextprotocol/sdk/client/stdio.js');
-    const client = new Client({ name: 'remcp-doctor', version: VERSION });
-    const stdio = new StdioClientTransport({ command: process.execPath, args: [entry], env: { ...process.env }, maxBufferSize: 4 * 1024 * 1024 });
-    const stderr = [];
-    stdio.onerror = error => stderr.push(String(error?.message || error));
-    await client.connect(stdio);
-    diagnosis.runtimeVersion = client.getServerVersion()?.version || 'unknown';
-    const tools = await client.listTools(undefined, { timeout: 20000 });
-    diagnosis.tools = tools.tools.length;
-    diagnosis.verdict = 'ok';
-    await client.close();
-    return diagnosis;
-  } catch (error) {
-    diagnosis.verdict = 'runtime-handshake-failed';
-    diagnosis.error = error instanceof Error ? error.message : String(error);
-    diagnosis.hint = 'Run the entry above by hand to see its output, then reinstall with: npx --yes @remcp/remcp@latest update';
-    return diagnosis;
-  }
-}
-
-// Reads the version a freshly installed global package reports, so an update that installed
-// nothing (wrong prefix, npm cache, permissions) is reported instead of assumed successful.
-// The roots the runtime is allowed to work in, as the person configured them. An empty list means
-// "the whole file system", so the doctor probes the home directory instead of guessing a root.
-function runtimeAllowedRoots() {
-  try {
-    const configured = JSON.parse(fs.readFileSync(runtimeConfigFile, 'utf8')).allowedRoots;
-    if (Array.isArray(configured) && configured.length) return configured.map(root => String(root).replace(/^~/, os.homedir()));
-  } catch {}
-  return [os.homedir()];
-}
-
-function installedVersion(packageName) {
-  const prefix = spawnSync(npm.command, [...npm.args, 'prefix', '--global'], { encoding: 'utf8' });
-  if (prefix.error || prefix.status !== 0) return null;
-  const manifest = path.join(String(prefix.stdout || '').trim(), 'lib', 'node_modules', ...packageName.split('/'), 'package.json');
-  try { return JSON.parse(fs.readFileSync(manifest, 'utf8')).version || null; } catch { return null; }
-}
-
-function uninstallPersistentService() {
-  const platform = servicePlatform();
-  if (platform === 'linux') {
-    spawnSync('systemctl', ['--user', 'disable', '--now', 'remcp-agent.service'], { stdio: 'inherit' });
-    try { fs.unlinkSync(linuxServiceFile); } catch {}
-    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'inherit' });
-  } else if (platform === 'darwin') {
-    const domain = macLaunchDomain();
-    spawnSync('launchctl', ['bootout', domain, macServiceFile], { stdio: 'ignore' });
-    try { fs.unlinkSync(macServiceFile); } catch {}
-  } else if (platform === 'win32') {
-    spawnSync('schtasks.exe', ['/End', '/TN', windowsTaskName], { stdio: 'ignore' });
-    spawnSync('schtasks.exe', ['/Delete', '/TN', windowsTaskName, '/F'], { stdio: 'ignore' });
-  }
-}
-
-function assertRuntimeTrust(server, flags) {
-  const origin = new URL(server).origin;
-  if (origin !== officialOrigin && !flags['trust-runtime']) {
-    throw new Error('Custom servers can provide local runtime metadata. Re-run with --trust-runtime only if you trust that server.');
-  }
-}
-
 function printHelp() {
   console.log(`ReMCP ${VERSION}\n\nCommands:\n  remcp start\n  remcp status\n  remcp doctor\n  remcp update\n  remcp install\n  remcp uninstall\n  remcp uninstall --purge\n  remcp telemetry [status|on|off]\n  remcp godmode [status|on|off]\n  remcp --version\n\nPairing commands are generated in the ReMCP workspace.\n\nUsage metrics are opt-out (tool names, timings, outcomes only, sent to your own ReMCP\naccount through the paired agent). Disable them at any time with: remcp telemetry off\n\nUnrestricted mode (remcp godmode on) lifts the access roots and the command guardrails for this\ncomputer only. It is deliberately not reachable from a model or an MCP tool.`);
 }
@@ -739,4 +278,4 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   printHelp();
-}
+}