@remcp/remcp 0.2.173 → 0.2.175

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/remcp",
-  "version": "0.2.173",
+  "version": "0.2.175",
   "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/agent-responder.mjs && node --check src/agent-update-monitor.mjs && node --check src/agent-update.mjs && node --check src/agent-utilities.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/npm-global.mjs && node --check src/cli/service-inventory.mjs && node --check src/cli/service.mjs && node --check src/cli/shell.mjs && node --check src/cli/update.mjs && node --check src/cli/windows-supervisor.mjs && node --check src/fs-access.mjs && node --check src/npm.mjs && node --check src/runtime.mjs && node --check src/version.mjs",
+    "check": "node --check bin/remcp.mjs && node --check src/agent-relay-connection.mjs && node --check src/agent-responder.mjs && node --check src/agent-runtime-capabilities.mjs && node --check src/agent-update-monitor.mjs && node --check src/agent-update.mjs && node --check src/agent-utilities.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/npm-global.mjs && node --check src/cli/service-inventory.mjs && node --check src/cli/service-macos.mjs && node --check src/cli/service-paths.mjs && node --check src/cli/service.mjs && node --check src/cli/shell.mjs && node --check src/cli/update.mjs && node --check src/cli/windows-supervisor.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/agent-relay-connection.mjs

@@ -0,0 +1,168 @@
+// Agent relay WebSocket lifecycle, bounded reconnect scheduling and handshake security.
+import os from 'node:os';
+import process from 'node:process';
+import WebSocket from 'ws';
+import { VERSION } from './version.mjs';
+import { boundedReconnectDelay, jitter, sendRelayMessage } from './agent-utilities.mjs';
+
+const RECONNECT_BASE_MS = 2_000;
+const RECONNECT_FIRST_MS = 500;
+const RECONNECT_MAX_MS = 60_000;
+
+// Higher-level agent owns runtime supervision/telemetry; this controller owns only relay transport.
+export function createAgentRelayConnection({
+  agentUrl, serverUrl, deviceToken, deviceId, deviceName,
+  isStopping, markStopping, getReconnects, setReconnects,
+  setSocket, getHelloState, respond, inFlight,
+  sendMetricsSample, reportInstallOnce, flushTelemetry,
+  checkForUpdate, schedulePostConnectUpdateChecks, clearPostConnectUpdateChecks, stop,
+}) {
+  let revoked = false;
+  let reconnectTimer = null;
+  let askedToReconnect = false;
+  let requestedReconnectDelayMs = 0;
+  function scheduleReconnect(delay) {
+    if (isStopping() || revoked || reconnectTimer) return;
+    // Keep the upper-bound guard in control flow immediately before the timer sink. CodeQL's
+    // resource-exhaustion model treats this as a barrier, and future callers cannot retain the
+    // agent with an attacker-controlled timer lifetime.
+    const numericDelay = Number(delay);
+    if (!Number.isFinite(numericDelay)) {
+      scheduleReconnect(RECONNECT_BASE_MS);
+      return;
+    }
+    if (numericDelay > RECONNECT_MAX_MS) {
+      scheduleReconnect(RECONNECT_MAX_MS);
+      return;
+    }
+    const safeDelay = Math.max(100, Math.floor(numericDelay));
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, safeDelay);
+    reconnectTimer.unref?.();
+  }
+
+  function scheduleBackoffReconnect() {
+    if (isStopping() || revoked || reconnectTimer) return;
+    setReconnects(getReconnects() + 1);
+    // The first retry after an unexpected drop is quick on purpose: a deploy blip, a proxy restart or
+    // a dropped packet should cost a fraction of a second, not the two seconds the backoff starts at.
+    const delay = getReconnects() === 1
+      ? jitter(RECONNECT_FIRST_MS)
+      : jitter(Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** Math.min(getReconnects(), 5)));
+    scheduleReconnect(delay);
+  }
+
+  function connect() {
+    if (isStopping()) return;
+    // The device token is intentionally sent only to the configured ReMCP relay during the
+    // authenticated WebSocket handshake.
+    // codeql[js/file-access-to-http]
+    const ws = new WebSocket(agentUrl, { headers: { Authorization: `Bearer ${deviceToken}` } });
+    // The ws client leaves cleanup/retry to the caller when an unexpected-response listener exists.
+    // A temporary workspace pause therefore needs an explicit retry; otherwise the first 423 leaves
+    // this WebSocket stuck in CONNECTING forever and turning the device back on cannot recover it.
+    ws.on('unexpected-response', (request, response) => {
+      const handshakeRevoked = String(response.headers['x-remcp-revoked'] || '') === '1';
+      const handshakeDisabled = String(response.headers['x-remcp-disabled'] || '') === '1';
+      if (handshakeRevoked) revoked = true;
+      console.error(`ReMCP relay refused the connection (HTTP ${response.statusCode})${handshakeRevoked ? ': this device was revoked' : handshakeDisabled ? ': this device is temporarily disabled' : ''}.`);
+      response.resume();
+      request.destroy();
+      if (handshakeDisabled && !revoked) {
+        setReconnects(getReconnects() + 1);
+        // 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();
+      }
+    });
+    setSocket(ws);
+    ws.on('open', () => {
+      if (reconnectTimer) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+      }
+      setReconnects(0);
+      sendRelayMessage(ws, {
+        type: 'hello',
+        deviceId,
+        deviceName,
+        hostname: os.hostname(),
+        platform: process.platform,
+        arch: process.arch,
+        agentVersion: VERSION,
+        ...getHelloState(),
+        reconnects: getReconnects(),
+      });
+      console.log(`Connected to ${serverUrl} as ${deviceName}`);
+      sendMetricsSample();
+      reportInstallOnce();
+      flushTelemetry();
+      void checkForUpdate();
+      schedulePostConnectUpdateChecks();
+    });
+    ws.on('message', raw => {
+      let message;
+      try { message = JSON.parse(raw.toString()); } catch { return; }
+      if (message?.type === 'reconnect') {
+        askedToReconnect = true;
+        requestedReconnectDelayMs = boundedReconnectDelay(message.delayMs, 150);
+        return;
+      }
+      if (message?.type === 'request') void respond(ws, message);
+      if (message?.type === 'cancel' && message.id) {
+        const controller = inFlight.get(message.id);
+        if (controller) controller.abort();
+      }
+    });
+    ws.on('close', code => {
+      clearPostConnectUpdateChecks();
+      for (const controller of inFlight.values()) controller.abort();
+      if (isStopping()) return;
+      // 1013 ('reconnect') is what a replica sends before it is replaced by a deployment. The machine
+      // is not down, it is moving: reconnect at once and forget the backoff, so the person and the
+      // model see nothing at all.
+      if (code === 1013 || askedToReconnect) {
+        const delayMs = requestedReconnectDelayMs || 150;
+        askedToReconnect = false;
+        requestedReconnectDelayMs = 0;
+        setReconnects(0);
+        console.log(`ReMCP relay is being redeployed; reconnecting in ${delayMs}ms.`);
+        scheduleReconnect(delayMs);
+        return;
+      }
+      if (code === 1008 || revoked) {
+        // The relay closes with 1008 when the device was revoked. Retrying forever would
+        // hide that from the person at the computer.
+        console.error('ReMCP access for this device was revoked. Pair the machine again from the ReMCP workspace: remcp connect --server <url> --code <code> --install');
+        return;
+      }
+      if (code === 1012) {
+        // 1012 ('service restart') is what the relay sends when another agent process took over this
+        // device. Staying alive would keep a second runtime and a reconnect loop, so this process
+        // stops and leaves the device to the agent that owns the connection.
+        console.error('Another ReMCP agent connected for this device; this process will stop. Run one agent per machine (a service manager or the remcp start command).');
+        markStopping();
+        void stop().finally(() => setTimeout(() => process.exit(0), 100));
+        return;
+      }
+      scheduleBackoffReconnect();
+    });
+    ws.on('error', error => console.error(`ReMCP relay: ${error.message}`));
+  }
+
+  return {
+    connect,
+    clearReconnect() { if (reconnectTimer) clearTimeout(reconnectTimer); reconnectTimer = null; },
+  };
+}

package/src/agent-runtime-capabilities.mjs

@@ -0,0 +1,56 @@
+// Maintains the local MCP runtime tool cache and bounded retry lifecycle.
+// The paired-agent connection owns the transport; this module owns only capabilities.
+export function normalizeRuntimeToolNames(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);
+}
+
+export function createRuntimeCapabilities({
+  getTools, setTools, isActive, announce, jitter, onError = console.error,
+  retryBaseMs = 1_000, retryMaxMs = 30_000,
+}) {
+  let retryDelay = retryBaseMs;
+  let retryTimer = null;
+
+  function clearRetry() {
+    if (retryTimer) clearTimeout(retryTimer);
+    retryTimer = null;
+    retryDelay = retryBaseMs;
+  }
+
+  function apply(next, { announce: shouldAnnounce = true } = {}) {
+    const current = getTools();
+    if (next.length === current.length && next.every((name, index) => name === current[index])) return current;
+    setTools(next);
+    if (shouldAnnounce) announce(next);
+    return next;
+  }
+
+  function scheduleRetry(client) {
+    if (!isActive(client) || retryTimer) return;
+    const delay = jitter(retryDelay);
+    retryDelay = Math.min(retryMaxMs, retryDelay * 2);
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void refresh(client);
+    }, delay);
+    retryTimer.unref?.();
+  }
+
+  async function refresh(client, { announce: shouldAnnounce = true } = {}) {
+    if (!client || !isActive(client)) return getTools();
+    try {
+      const listed = await client.listTools(undefined, { timeout: 3000 });
+      // A list request can settle after reconnect/restart. Never publish stale capabilities.
+      if (!isActive(client)) return getTools();
+      clearRetry();
+      apply(normalizeRuntimeToolNames(listed), { announce: shouldAnnounce });
+    } catch (error) {
+      onError(`ReMCP could not refresh runtime capabilities: ${error instanceof Error ? error.message : String(error)}`);
+      scheduleRetry(client);
+    }
+    return getTools();
+  }
+
+  return { apply, clearRetry, refresh, scheduleRetry };
+}

package/src/agent.mjs

@@ -1,32 +1,26 @@
 import os from 'node:os';
 import process from 'node:process';
-import WebSocket from 'ws';
 import { Client } from '@modelcontextprotocol/client';
 import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
 import { VERSION } from './version.mjs';
 import { localRuntimeEntry } from './agent-update.mjs';
 
 export { localRuntimeEntry, supervisorRestart, updateDecision } from './agent-update.mjs';
-import { normalizedServerUrl, sendRelayMessage, jitter, boundedReconnectDelay, deviceMetrics } from './agent-utilities.mjs';
+import { normalizedServerUrl, sendRelayMessage, jitter, deviceMetrics } from './agent-utilities.mjs';
 import { createAgentUpdateMonitor, UPDATE_CHECK_INTERVAL_MS } from './agent-update-monitor.mjs';
 import { createAgentResponder } from './agent-responder.mjs';
+import { createAgentRelayConnection } from './agent-relay-connection.mjs';
+import { createRuntimeCapabilities, normalizeRuntimeToolNames } from './agent-runtime-capabilities.mjs';
 
 const METRICS_INTERVAL_MS = 5 * 60_000;
 const TELEMETRY_QUEUE_LIMIT = 500;
 const TELEMETRY_BATCH_LIMIT = 100;
 const TELEMETRY_SEND_INTERVAL_MS = 5_000;
-const RECONNECT_BASE_MS = 2_000;
-// The first retry after an unexpected drop: fast enough that a blip is invisible, slow enough not to
-// hammer a server that is genuinely down.
-const RECONNECT_FIRST_MS = 500;
 // Must stay above the runtime's own output ceiling (8 MiB), otherwise a large but legal tool result
 // closes the stdio connection and restarts the runtime mid-call.
 const RUNTIME_STDIO_BUFFER_BYTES = 24 * 1024 * 1024;
-const RECONNECT_MAX_MS = 60_000;
 const RUNTIME_RESTART_BASE_MS = 1_000;
 const RUNTIME_RESTART_MAX_MS = 30_000;
-const RUNTIME_TOOLS_RETRY_BASE_MS = 1_000;
-const RUNTIME_TOOLS_RETRY_MAX_MS = 30_000;
 // Below the relay's RPC timeout so the model gets a real error instead of a client-side
 // timeout while the device keeps working invisibly.
 const CALL_TIMEOUT_MARGIN_MS = 10_000;
@@ -43,14 +37,9 @@ export async function runAgent(options) {
   const metricsIntervalMs = Math.max(60_000, Number(options.metricsIntervalMs || process.env.REMCP_AGENT_METRICS_INTERVAL_MS) || METRICS_INTERVAL_MS);
   const persistState = typeof options.persistState === 'function' ? options.persistState : () => {};
   let stopping = false;
-  let revoked = false;
   const inFlight = new Map();
   let activeSocket;
   let reconnects = 0;
-  let reconnectTimer = null;
-  // Set when a replica asks this agent to move before it is replaced; the close handler reads it.
-  let askedToReconnect = false;
-  let requestedReconnectDelayMs = 0;
   let pendingRequests = 0;
   let runtimeVersion = 'unknown';
   let runtimeRestarts = 0;
@@ -81,8 +70,6 @@ export async function runAgent(options) {
   let transport = null;
   let runtimeRestartDelay = RUNTIME_RESTART_BASE_MS;
   let runtimeRestartTimer = null;
-  let runtimeToolsRetryDelay = RUNTIME_TOOLS_RETRY_BASE_MS;
-  let runtimeToolsRetryTimer = null;
   let stopPromise = null;
 
   function runtimeEnv() {
@@ -97,51 +84,20 @@ 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);
-  }
-
-  function scheduleRuntimeToolsRetry(client) {
-    if (stopping || runtimeDown || mcp !== client || runtimeToolsRetryTimer) return;
-    const delay = jitter(runtimeToolsRetryDelay);
-    runtimeToolsRetryDelay = Math.min(RUNTIME_TOOLS_RETRY_MAX_MS, runtimeToolsRetryDelay * 2);
-    runtimeToolsRetryTimer = setTimeout(() => {
-      runtimeToolsRetryTimer = null;
-      void refreshRuntimeTools(client);
-    }, delay);
-    runtimeToolsRetryTimer.unref?.();
-  }
-
-  function applyRuntimeTools(next, { announce = true } = {}) {
-    if (next.length === runtimeTools.length && next.every((name, index) => name === runtimeTools[index])) return runtimeTools;
-    runtimeTools = next;
-    if (announce) send({ type: 'capabilities', runtimeTools });
-    return runtimeTools;
-  }
-
-  async function refreshRuntimeTools(client = mcp, { announce = true } = {}) {
-    if (!client || runtimeDown) return runtimeTools;
-    try {
-      const listed = await client.listTools(undefined, { timeout: 3000 });
-      if (runtimeToolsRetryTimer) clearTimeout(runtimeToolsRetryTimer);
-      runtimeToolsRetryTimer = null;
-      runtimeToolsRetryDelay = RUNTIME_TOOLS_RETRY_BASE_MS;
-      applyRuntimeTools(toolNames(listed), { announce });
-    } catch (error) {
-      console.error(`ReMCP could not refresh runtime capabilities: ${error instanceof Error ? error.message : String(error)}`);
-      scheduleRuntimeToolsRetry(client);
-    }
-    return runtimeTools;
-  }
+  const runtimeCapabilities = createRuntimeCapabilities({
+    getTools: () => runtimeTools,
+    setTools: next => { runtimeTools = next; },
+    isActive: client => !stopping && !runtimeDown && mcp === client,
+    announce: next => send({ type: 'capabilities', runtimeTools: next }),
+    jitter,
+  });
+  const refreshRuntimeTools = (client = mcp, options) => runtimeCapabilities.refresh(client, options);
 
   async function startRuntime() {
     if (stopping) return;
     clearTimeout(runtimeRestartTimer);
     runtimeRestartTimer = null;
-    if (runtimeToolsRetryTimer) clearTimeout(runtimeToolsRetryTimer);
-    runtimeToolsRetryTimer = null;
-    runtimeToolsRetryDelay = RUNTIME_TOOLS_RETRY_BASE_MS;
+    runtimeCapabilities.clearRetry();
     runtimeDown = true;
     const previous = mcp;
     mcp = null;
@@ -168,10 +124,11 @@ export async function runAgent(options) {
             onChanged(error, tools) {
               if (error) {
                 console.error(`ReMCP runtime tool subscription failed: ${error instanceof Error ? error.message : String(error)}`);
-                scheduleRuntimeToolsRetry(client);
+                runtimeCapabilities.scheduleRetry(client);
                 return;
               }
-              applyRuntimeTools(toolNames({ tools }));
+              if (mcp !== client || runtimeDown || stopping) return;
+              runtimeCapabilities.apply(normalizeRuntimeToolNames({ tools }));
             },
           },
         },
@@ -219,9 +176,7 @@ export async function runAgent(options) {
 
   function handleRuntimeExit(reason) {
     if (stopping || runtimeRestartTimer) return;
-    if (runtimeToolsRetryTimer) clearTimeout(runtimeToolsRetryTimer);
-    runtimeToolsRetryTimer = null;
-    runtimeToolsRetryDelay = RUNTIME_TOOLS_RETRY_BASE_MS;
+    runtimeCapabilities.clearRetry();
     runtimeDown = true;
     runtimeTools = [];
     send({ type: 'capabilities', runtimeTools });
@@ -290,39 +245,6 @@ export async function runAgent(options) {
     }
   }
 
-  function scheduleReconnect(delay) {
-    if (stopping || revoked || reconnectTimer) return;
-    // Keep the upper-bound guard in control flow immediately before the timer sink. CodeQL's
-    // resource-exhaustion model treats this as a barrier, and future callers cannot retain the
-    // agent with an attacker-controlled timer lifetime.
-    const numericDelay = Number(delay);
-    if (!Number.isFinite(numericDelay)) {
-      scheduleReconnect(RECONNECT_BASE_MS);
-      return;
-    }
-    if (numericDelay > RECONNECT_MAX_MS) {
-      scheduleReconnect(RECONNECT_MAX_MS);
-      return;
-    }
-    const safeDelay = Math.max(100, Math.floor(numericDelay));
-    reconnectTimer = setTimeout(() => {
-      reconnectTimer = null;
-      connect();
-    }, safeDelay);
-    reconnectTimer.unref?.();
-  }
-
-  function scheduleBackoffReconnect() {
-    if (stopping || revoked || reconnectTimer) return;
-    reconnects += 1;
-    // The first retry after an unexpected drop is quick on purpose: a deploy blip, a proxy restart or
-    // a dropped packet should cost a fraction of a second, not the two seconds the backoff starts at.
-    const delay = reconnects === 1
-      ? jitter(RECONNECT_FIRST_MS)
-      : jitter(Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** Math.min(reconnects, 5)));
-    scheduleReconnect(delay);
-  }
-
   const respond = createAgentResponder({
     inFlight,
     onPendingChange: delta => { pendingRequests = Math.max(0, pendingRequests + delta); },
@@ -349,116 +271,23 @@ export async function runAgent(options) {
     },
   });
 
-  function connect() {
-    if (stopping) return;
-    // The device token is intentionally sent only to the configured ReMCP relay during the
-    // authenticated WebSocket handshake.
-    // codeql[js/file-access-to-http]
-    const ws = new WebSocket(agentUrl, { headers: { Authorization: `Bearer ${deviceToken}` } });
-    // The ws client leaves cleanup/retry to the caller when an unexpected-response listener exists.
-    // A temporary workspace pause therefore needs an explicit retry; otherwise the first 423 leaves
-    // this WebSocket stuck in CONNECTING forever and turning the device back on cannot recover it.
-    ws.on('unexpected-response', (request, response) => {
-      const handshakeRevoked = String(response.headers['x-remcp-revoked'] || '') === '1';
-      const handshakeDisabled = String(response.headers['x-remcp-disabled'] || '') === '1';
-      if (handshakeRevoked) revoked = true;
-      console.error(`ReMCP relay refused the connection (HTTP ${response.statusCode})${handshakeRevoked ? ': this device was revoked' : handshakeDisabled ? ': this device is temporarily disabled' : ''}.`);
-      response.resume();
-      request.destroy();
-      if (handshakeDisabled && !revoked) {
-        reconnects += 1;
-        // 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;
-    ws.on('open', () => {
-      if (reconnectTimer) {
-        clearTimeout(reconnectTimer);
-        reconnectTimer = null;
-      }
-      reconnects = 0;
-      sendRelayMessage(ws, {
-        type: 'hello',
-        deviceId,
-        deviceName,
-        hostname: os.hostname(),
-        platform: process.platform,
-        arch: process.arch,
-        agentVersion: VERSION,
-        runtimeVersion,
-        runtimeState: runtimeDown ? 'down' : 'ready',
-        runtimeError,
-        runtimeTools,
-        telemetryEnabled,
-        reconnects,
-      });
-      console.log(`Connected to ${serverUrl} as ${deviceName}`);
-      sendMetricsSample();
-      reportInstallOnce();
-      flushTelemetry();
-      void checkForUpdate();
-      schedulePostConnectUpdateChecks();
-    });
-    ws.on('message', raw => {
-      let message;
-      try { message = JSON.parse(raw.toString()); } catch { return; }
-      if (message?.type === 'reconnect') {
-        askedToReconnect = true;
-        requestedReconnectDelayMs = boundedReconnectDelay(message.delayMs, 150);
-        return;
-      }
-      if (message?.type === 'request') void respond(ws, message);
-      if (message?.type === 'cancel' && message.id) {
-        const controller = inFlight.get(message.id);
-        if (controller) controller.abort();
-      }
-    });
-    ws.on('close', code => {
-      clearPostConnectUpdateChecks();
-      for (const controller of inFlight.values()) controller.abort();
-      if (stopping) return;
-      // 1013 ('reconnect') is what a replica sends before it is replaced by a deployment. The machine
-      // is not down, it is moving: reconnect at once and forget the backoff, so the person and the
-      // model see nothing at all.
-      if (code === 1013 || askedToReconnect) {
-        const delayMs = requestedReconnectDelayMs || 150;
-        askedToReconnect = false;
-        requestedReconnectDelayMs = 0;
-        reconnects = 0;
-        console.log(`ReMCP relay is being redeployed; reconnecting in ${delayMs}ms.`);
-        scheduleReconnect(delayMs);
-        return;
-      }
-      if (code === 1008 || revoked) {
-        // The relay closes with 1008 when the device was revoked. Retrying forever would
-        // hide that from the person at the computer.
-        console.error('ReMCP access for this device was revoked. Pair the machine again from the ReMCP workspace: remcp connect --server <url> --code <code> --install');
-        return;
-      }
-      if (code === 1012) {
-        // 1012 ('service restart') is what the relay sends when another agent process took over this
-        // device. Staying alive would keep a second runtime and a reconnect loop, so this process
-        // stops and leaves the device to the agent that owns the connection.
-        console.error('Another ReMCP agent connected for this device; this process will stop. Run one agent per machine (a service manager or the remcp start command).');
-        stopping = true;
-        void stop().finally(() => setTimeout(() => process.exit(0), 100));
-        return;
-      }
-      scheduleBackoffReconnect();
-    });
-    ws.on('error', error => console.error(`ReMCP relay: ${error.message}`));
-  }
+  const { connect, clearReconnect } = createAgentRelayConnection({
+    agentUrl, serverUrl, deviceToken, deviceId, deviceName,
+    isStopping: () => stopping,
+    markStopping: () => { stopping = true; },
+    getReconnects: () => reconnects,
+    setReconnects: count => { reconnects = count; },
+    setSocket: socket => { activeSocket = socket; },
+    getHelloState: () => ({
+      runtimeVersion,
+      runtimeState: runtimeDown ? 'down' : 'ready',
+      runtimeError,
+      runtimeTools,
+      telemetryEnabled,
+    }),
+    respond, inFlight, sendMetricsSample, reportInstallOnce, flushTelemetry,
+    checkForUpdate, schedulePostConnectUpdateChecks, clearPostConnectUpdateChecks, stop,
+  });
 
   scheduleMetricsSample();
   const telemetryFlushTimer = setInterval(flushTelemetry, TELEMETRY_SEND_INTERVAL_MS);
@@ -470,10 +299,8 @@ export async function runAgent(options) {
     if (stopPromise) return stopPromise;
     stopping = true;
     clearTimeout(runtimeRestartTimer);
-    clearTimeout(runtimeToolsRetryTimer);
-    runtimeToolsRetryTimer = null;
-    clearTimeout(reconnectTimer);
-    reconnectTimer = null;
+    runtimeCapabilities.clearRetry();
+    clearReconnect();
     clearPostConnectUpdateChecks();
     if (telemetryTimer) clearTimeout(telemetryTimer);
     clearInterval(telemetryFlushTimer);

package/src/cli/service-macos.mjs

@@ -0,0 +1,192 @@
+// macOS launchd service and managed CLI shim; no Linux/Windows service side effects.
+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 { globalCliPath, servicePlatform } from './npm-global.mjs';
+import { persistentServiceExpected, canonicalServiceCliPath, canonicalServiceNodePath } from './service-inventory.mjs';
+import { configDir, home, macLogFile, macServiceFile, macServiceLabel } from './env.mjs';
+import { run } from './shell.mjs';
+import { resolvedCliScript, shellQuote, xmlEscape } from './service-paths.mjs';
+
+export function macLaunchDomain() {
+  if (typeof process.getuid !== 'function') throw new Error('Could not determine the current macOS user');
+  return `gui/${process.getuid()}`;
+}
+
+const remcpPathBlockStart = '# >>> ReMCP CLI PATH >>>';
+const remcpPathBlockEnd = '# <<< ReMCP CLI PATH <<<';
+const remcpCliShimMarker = '# ReMCP managed CLI shim';
+
+function macCliShimPath() {
+  return path.join(home, '.local', 'bin', 'remcp');
+}
+
+function interactiveShellProfile() {
+  const shell = String(process.env.REMCP_TEST_SHELL || process.env.SHELL || os.userInfo().shell || '/bin/zsh');
+  const name = path.basename(shell);
+  if (name === 'zsh') return path.join(home, '.zshrc');
+  if (name === 'bash') return path.join(home, '.bash_profile');
+  return '';
+}
+
+function upsertManagedPathBlock(file) {
+  if (!file) return false;
+  const block = [
+    remcpPathBlockStart,
+    'case ":$PATH:" in',
+    '  *":$HOME/.local/bin:"*) ;;',
+    '  *) export PATH="$HOME/.local/bin:$PATH" ;;',
+    'esac',
+    remcpPathBlockEnd,
+  ].join('\n');
+  let current = '';
+  try { current = fs.readFileSync(file, 'utf8'); } catch {}
+  const start = current.indexOf(remcpPathBlockStart);
+  const end = start >= 0 ? current.indexOf(remcpPathBlockEnd, start + remcpPathBlockStart.length) : -1;
+  let next;
+  if (start >= 0 && end >= 0) {
+    next = current.slice(0, start) + block + current.slice(end + remcpPathBlockEnd.length);
+  } else {
+    const prefix = current && !current.endsWith('\n') ? current + '\n' : current;
+    next = prefix + (prefix ? '\n' : '') + block + '\n';
+  }
+  if (next === current) return false;
+  fs.writeFileSync(file, next, { mode:0o600 });
+  return true;
+}
+
+function removeManagedPathBlock(file) {
+  if (!file) return;
+  let current = '';
+  try { current = fs.readFileSync(file, 'utf8'); } catch { return; }
+  const start = current.indexOf(remcpPathBlockStart);
+  const end = start >= 0 ? current.indexOf(remcpPathBlockEnd, start + remcpPathBlockStart.length) : -1;
+  if (start < 0 || end < 0) return;
+  let before = current.slice(0, start);
+  let after = current.slice(end + remcpPathBlockEnd.length);
+  if (before.endsWith('\n') && after.startsWith('\n')) after = after.slice(1);
+  const next = before + after;
+  fs.writeFileSync(file, next, { mode:0o600 });
+}
+
+export function ensureMacCliCommand(config = {}, { cliPath = '', nodePath = '' } = {}) {
+  if (servicePlatform() !== 'darwin') return null;
+  const effectiveCli = cliPath || (persistentServiceExpected(config) ? canonicalServiceCliPath(config) : globalCliPath());
+  const effectiveNode = nodePath || (persistentServiceExpected(config) ? canonicalServiceNodePath(config) : process.execPath);
+  const cliScript = resolvedCliScript(effectiveCli);
+  const shim = macCliShimPath();
+  try {
+    const existing = fs.readFileSync(shim, 'utf8');
+    if (!existing.includes(remcpCliShimMarker)) {
+      console.error(`ReMCP did not replace ${shim} because it is not a ReMCP-managed command.`);
+      return null;
+    }
+  } catch (error) {
+    if (error?.code && error.code !== 'ENOENT') {
+      console.error(`ReMCP could not inspect ${shim}: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+  }
+  const launcher = `#!/bin/sh\n${remcpCliShimMarker}\nexec ${shellQuote(effectiveNode)} ${shellQuote(cliScript)} "$@"\n`;
+  fs.mkdirSync(path.dirname(shim), { recursive:true, mode:0o755 });
+  const temporary = `${shim}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, launcher, { mode:0o755 });
+  fs.chmodSync(temporary, 0o755);
+  fs.renameSync(temporary, shim);
+  upsertManagedPathBlock(interactiveShellProfile());
+  return shim;
+}
+
+export function removeMacCliCommand() {
+  if (servicePlatform() !== 'darwin') return;
+  const shim = macCliShimPath();
+  try {
+    const existing = fs.readFileSync(shim, 'utf8');
+    if (existing.includes(remcpCliShimMarker)) fs.unlinkSync(shim);
+  } catch {}
+  removeManagedPathBlock(interactiveShellProfile());
+}
+
+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(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`;
+}
+
+export function macJobLoaded(target) {
+  return spawnSync('launchctl', ['print', target], { stdio: 'ignore' }).status === 0;
+}
+
+function submitMacHelper(kind, lines) {
+  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  const nonce = `${process.pid}.${Date.now()}`;
+  const helperFile = path.join(configDir, `launchd-${kind}-${nonce}.sh`);
+  const helperLabel = `${macServiceLabel}.${kind}.${nonce}`;
+  const script = [
+    '#!/bin/sh',
+    'sleep 1',
+    'status=0',
+    ...lines.map(line => `${line} || status=$?`),
+    `if [ "$status" -ne 0 ]; then echo "ReMCP launchd ${kind} helper failed with status $status" >> ${shellQuote(macLogFile)}; fi`,
+    `rm -f ${shellQuote(helperFile)}`,
+    `launchctl remove ${shellQuote(helperLabel)} >/dev/null 2>&1 || true`,
+    'exit 0',
+    '',
+  ].join('\n');
+  fs.writeFileSync(helperFile, script, { mode: 0o700 });
+  fs.chmodSync(helperFile, 0o700);
+  run('launchctl', ['submit', '-l', helperLabel, '--', '/bin/sh', helperFile]);
+  return helperLabel;
+}
+
+function scheduleMacServiceReload(domain, target) {
+  return submitMacHelper('reload', [
+    `launchctl bootout ${shellQuote(target)} >/dev/null 2>&1 || true`,
+    `launchctl bootstrap ${shellQuote(domain)} ${shellQuote(macServiceFile)}`,
+    `launchctl enable ${shellQuote(target)}`,
+    `launchctl kickstart -k ${shellQuote(target)}`,
+  ]);
+}
+
+export function scheduleMacServiceRestart(target) {
+  return submitMacHelper('restart', [
+    `launchctl kickstart -k ${shellQuote(target)}`,
+  ]);
+}
+
+export function installMacService(cliPath = globalCliPath(), { restart = true, nodePath = process.execPath } = {}) {
+  const domain = macLaunchDomain();
+  const target = `${domain}/${macServiceLabel}`;
+  const plist = macServicePlist(cliPath, nodePath);
+  let previous = '';
+  try { previous = fs.readFileSync(macServiceFile, 'utf8'); } catch {}
+  const loaded = macJobLoaded(target);
+
+  fs.mkdirSync(path.dirname(macServiceFile), { recursive: true });
+  fs.mkdirSync(path.dirname(macLogFile), { recursive: true });
+  fs.writeFileSync(macServiceFile, plist, { mode: 0o600 });
+
+  if (loaded && previous === plist) {
+    run('launchctl', ['enable', target]);
+    // Never boot out a healthy loaded job just to refresh an in-place npm install. The final
+    // kickstart keeps launchd responsible for bringing the replacement agent back.
+    if (restart) run('launchctl', ['kickstart', '-k', target]);
+    return 'loaded';
+  }
+
+  if (loaded) {
+    // A changed Node/npm prefix requires launchd to re-read ProgramArguments. A separate transient
+    // launchd job survives booting out com.remcp.agent even when the updater was launched by it.
+    scheduleMacServiceReload(domain, target);
+    return 'reload-scheduled';
+  }
+
+  run('launchctl', ['bootstrap', domain, macServiceFile]);
+  run('launchctl', ['enable', target]);
+  if (restart) run('launchctl', ['kickstart', '-k', target]);
+  return 'bootstrapped';
+}

package/src/cli/service-paths.mjs

@@ -0,0 +1,15 @@
+// Shared service launcher/path escaping across the three supported platforms.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function resolvedCliScript(cliPath) {
+  return fs.existsSync(cliPath) ? fs.realpathSync(cliPath) : path.resolve(cliPath);
+}
+
+export function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+export function xmlEscape(value) {
+  return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}

package/src/cli/service.mjs

@@ -5,26 +5,24 @@ export { persistentServiceExpected, persistentServiceState, releasePairPresentAt
 // 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 { resolveNpm } from '../npm.mjs';
+import { resolvedCliScript, shellQuote } from './service-paths.mjs';
+import { macLaunchDomain, ensureMacCliCommand, installMacService, macJobLoaded, scheduleMacServiceRestart, removeMacCliCommand } from './service-macos.mjs';
+export { xmlEscape } from './service-paths.mjs';
+export { macLaunchDomain, ensureMacCliCommand, installMacService } from './service-macos.mjs';
 import { PACKAGE_NAME, VERSION } from '../version.mjs';
 
 import { saveConfig } from './config.mjs';
-import { configDir, home, linuxServiceFile, linuxServiceLauncherFile, macLogFile, macServiceFile, macServiceLabel, npm, windowsServiceLauncherFile, windowsTaskName } from './env.mjs';
-import { output, run } from './shell.mjs';
+import { configDir, home, linuxServiceFile, linuxServiceLauncherFile, macServiceFile, macServiceLabel, windowsServiceLauncherFile, windowsTaskName } from './env.mjs';
+import { run } from './shell.mjs';
 import { windowsServiceLauncherText, windowsTaskReliabilityCommand } from './windows-supervisor.mjs';
 
 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`;
@@ -36,10 +34,6 @@ function writeLinuxServiceLauncher(cliPath = globalCliPath(), nodePath = process
   return linuxServiceLauncherFile;
 }
 
-export function xmlEscape(value) {
-  return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
-}
-
 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`;
@@ -49,191 +43,6 @@ export function installLinuxService(cliPath = globalCliPath(), nodePath = proces
   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()}`;
-}
-
-function shellQuote(value) {
-  return `'${String(value).replaceAll("'", "'\\''")}'`;
-}
-
-const remcpPathBlockStart = '# >>> ReMCP CLI PATH >>>';
-const remcpPathBlockEnd = '# <<< ReMCP CLI PATH <<<';
-const remcpCliShimMarker = '# ReMCP managed CLI shim';
-
-function macCliShimPath() {
-  return path.join(home, '.local', 'bin', 'remcp');
-}
-
-function interactiveShellProfile() {
-  const shell = String(process.env.REMCP_TEST_SHELL || process.env.SHELL || os.userInfo().shell || '/bin/zsh');
-  const name = path.basename(shell);
-  if (name === 'zsh') return path.join(home, '.zshrc');
-  if (name === 'bash') return path.join(home, '.bash_profile');
-  return '';
-}
-
-function upsertManagedPathBlock(file) {
-  if (!file) return false;
-  const block = [
-    remcpPathBlockStart,
-    'case ":$PATH:" in',
-    '  *":$HOME/.local/bin:"*) ;;',
-    '  *) export PATH="$HOME/.local/bin:$PATH" ;;',
-    'esac',
-    remcpPathBlockEnd,
-  ].join('\n');
-  let current = '';
-  try { current = fs.readFileSync(file, 'utf8'); } catch {}
-  const start = current.indexOf(remcpPathBlockStart);
-  const end = start >= 0 ? current.indexOf(remcpPathBlockEnd, start + remcpPathBlockStart.length) : -1;
-  let next;
-  if (start >= 0 && end >= 0) {
-    next = current.slice(0, start) + block + current.slice(end + remcpPathBlockEnd.length);
-  } else {
-    const prefix = current && !current.endsWith('\n') ? current + '\n' : current;
-    next = prefix + (prefix ? '\n' : '') + block + '\n';
-  }
-  if (next === current) return false;
-  fs.writeFileSync(file, next, { mode:0o600 });
-  return true;
-}
-
-function removeManagedPathBlock(file) {
-  if (!file) return;
-  let current = '';
-  try { current = fs.readFileSync(file, 'utf8'); } catch { return; }
-  const start = current.indexOf(remcpPathBlockStart);
-  const end = start >= 0 ? current.indexOf(remcpPathBlockEnd, start + remcpPathBlockStart.length) : -1;
-  if (start < 0 || end < 0) return;
-  let before = current.slice(0, start);
-  let after = current.slice(end + remcpPathBlockEnd.length);
-  if (before.endsWith('\n') && after.startsWith('\n')) after = after.slice(1);
-  const next = before + after;
-  fs.writeFileSync(file, next, { mode:0o600 });
-}
-
-export function ensureMacCliCommand(config = {}, { cliPath = '', nodePath = '' } = {}) {
-  if (servicePlatform() !== 'darwin') return null;
-  const effectiveCli = cliPath || (persistentServiceExpected(config) ? canonicalServiceCliPath(config) : globalCliPath());
-  const effectiveNode = nodePath || (persistentServiceExpected(config) ? canonicalServiceNodePath(config) : process.execPath);
-  const cliScript = resolvedCliScript(effectiveCli);
-  const shim = macCliShimPath();
-  try {
-    const existing = fs.readFileSync(shim, 'utf8');
-    if (!existing.includes(remcpCliShimMarker)) {
-      console.error(`ReMCP did not replace ${shim} because it is not a ReMCP-managed command.`);
-      return null;
-    }
-  } catch (error) {
-    if (error?.code && error.code !== 'ENOENT') {
-      console.error(`ReMCP could not inspect ${shim}: ${error instanceof Error ? error.message : String(error)}`);
-      return null;
-    }
-  }
-  const launcher = `#!/bin/sh\n${remcpCliShimMarker}\nexec ${shellQuote(effectiveNode)} ${shellQuote(cliScript)} "$@"\n`;
-  fs.mkdirSync(path.dirname(shim), { recursive:true, mode:0o755 });
-  const temporary = `${shim}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(temporary, launcher, { mode:0o755 });
-  fs.chmodSync(temporary, 0o755);
-  fs.renameSync(temporary, shim);
-  upsertManagedPathBlock(interactiveShellProfile());
-  return shim;
-}
-
-function removeMacCliCommand() {
-  if (servicePlatform() !== 'darwin') return;
-  const shim = macCliShimPath();
-  try {
-    const existing = fs.readFileSync(shim, 'utf8');
-    if (existing.includes(remcpCliShimMarker)) fs.unlinkSync(shim);
-  } catch {}
-  removeManagedPathBlock(interactiveShellProfile());
-}
-
-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(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) {
-  return spawnSync('launchctl', ['print', target], { stdio: 'ignore' }).status === 0;
-}
-
-function submitMacHelper(kind, lines) {
-  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
-  const nonce = `${process.pid}.${Date.now()}`;
-  const helperFile = path.join(configDir, `launchd-${kind}-${nonce}.sh`);
-  const helperLabel = `${macServiceLabel}.${kind}.${nonce}`;
-  const script = [
-    '#!/bin/sh',
-    'sleep 1',
-    'status=0',
-    ...lines.map(line => `${line} || status=$?`),
-    `if [ "$status" -ne 0 ]; then echo "ReMCP launchd ${kind} helper failed with status $status" >> ${shellQuote(macLogFile)}; fi`,
-    `rm -f ${shellQuote(helperFile)}`,
-    `launchctl remove ${shellQuote(helperLabel)} >/dev/null 2>&1 || true`,
-    'exit 0',
-    '',
-  ].join('\n');
-  fs.writeFileSync(helperFile, script, { mode: 0o700 });
-  fs.chmodSync(helperFile, 0o700);
-  run('launchctl', ['submit', '-l', helperLabel, '--', '/bin/sh', helperFile]);
-  return helperLabel;
-}
-
-function scheduleMacServiceReload(domain, target) {
-  return submitMacHelper('reload', [
-    `launchctl bootout ${shellQuote(target)} >/dev/null 2>&1 || true`,
-    `launchctl bootstrap ${shellQuote(domain)} ${shellQuote(macServiceFile)}`,
-    `launchctl enable ${shellQuote(target)}`,
-    `launchctl kickstart -k ${shellQuote(target)}`,
-  ]);
-}
-
-function scheduleMacServiceRestart(target) {
-  return submitMacHelper('restart', [
-    `launchctl kickstart -k ${shellQuote(target)}`,
-  ]);
-}
-
-export function installMacService(cliPath = globalCliPath(), { restart = true, nodePath = process.execPath } = {}) {
-  const domain = macLaunchDomain();
-  const target = `${domain}/${macServiceLabel}`;
-  const plist = macServicePlist(cliPath, nodePath);
-  let previous = '';
-  try { previous = fs.readFileSync(macServiceFile, 'utf8'); } catch {}
-  const loaded = macJobLoaded(target);
-
-  fs.mkdirSync(path.dirname(macServiceFile), { recursive: true });
-  fs.mkdirSync(path.dirname(macLogFile), { recursive: true });
-  fs.writeFileSync(macServiceFile, plist, { mode: 0o600 });
-
-  if (loaded && previous === plist) {
-    run('launchctl', ['enable', target]);
-    // Never boot out a healthy loaded job just to refresh an in-place npm install. The final
-    // kickstart keeps launchd responsible for bringing the replacement agent back.
-    if (restart) run('launchctl', ['kickstart', '-k', target]);
-    return 'loaded';
-  }
-
-  if (loaded) {
-    // A changed Node/npm prefix requires launchd to re-read ProgramArguments. A separate transient
-    // launchd job survives booting out com.remcp.agent even when the updater was launched by it.
-    scheduleMacServiceReload(domain, target);
-    return 'reload-scheduled';
-  }
-
-  run('launchctl', ['bootstrap', domain, macServiceFile]);
-  run('launchctl', ['enable', target]);
-  if (restart) run('launchctl', ['kickstart', '-k', target]);
-  return 'bootstrapped';
-}
-
 export function writeWindowsServiceLauncher(cliPath = globalCliPath(), nodePath = process.execPath) {
   const launcher = windowsServiceLauncherText(cliPath, nodePath);
   fs.mkdirSync(configDir, { recursive:true, mode:0o700 });