machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/service.mjs

@@ -1,14 +1,20 @@
-import { closeSync, constants as fsConstants, existsSync, ftruncateSync, lstatSync, mkdirSync, readSync, realpathSync, rmSync, statSync, writeSync } from "node:fs";
+import { closeSync, constants as fsConstants, existsSync, ftruncateSync, lstatSync, mkdirSync, readSync, realpathSync, statSync, writeSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { runExecutable } from "./shell.mjs";
-import { ensureOwnerOnlyDir, expandHome } from "./state.mjs";
+import { expandHome } from "./state.mjs";
+import { ensureOwnerOnlyDir } from "./secure-file.mjs";
 import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { openRegularFileSync, readBoundedRegularFileSync } from "./secure-file.mjs";
-import { waitForInactiveStatus } from "./service-convergence.mjs";
+import { waitForInactiveStatus, waitForStableActiveStatus, waitForStatus } from "./service-convergence.mjs";
+import { launchdStatusSummary, systemdStatusSummary } from "./service-status.mjs";
+import { systemdRemovalDecision } from "./systemd-removal.mjs";
+import { removeServiceDefinitionIfCurrent, snapshotServiceDefinition } from "./service-definition.mjs";
 import { writeServiceEnvironment } from "./service-environment.mjs";
+import { beginServiceOwnerUpdate, removeServiceOwner } from "./service-owner.mjs";
 import {
   installWindowsTask,
+  restartWindowsTask,
   startWindowsTask,
   statusWindowsTask,
   stopWindowsTask,
@@ -18,7 +24,8 @@ export { windowsCommandLineArgument } from "./windows-service.mjs";
 
 const LABEL = "dev.machine-bridge-mcp.daemon";
 const SERVICE_COMMAND_OUTPUT_BYTES = 64 * 1024;
-const AUTOSTART_LOG_SCHEMA_VERSION = 3;
+const SERVICE_COMMAND_TIMEOUT_MS = 30_000;
+const AUTOSTART_LOG_SCHEMA_VERSION = 4;
 
 function serviceRun(command, args) {
   return runServiceCommand(command, args);
@@ -28,24 +35,93 @@ export function runServiceCommand(command, args, execute = runExecutable) {
   return execute(command, args, {
     capture: true,
     allowFailure: true,
+    timeoutMs: SERVICE_COMMAND_TIMEOUT_MS,
     maxOutputBytes: SERVICE_COMMAND_OUTPUT_BYTES,
   });
 }
 
-export async function installAutostart({ workspace, stateRoot, entryScript, logger = console }) {
+export async function installAutostart({ workspace, stateRoot, entryScript, version, logger = console,
+  installProvider = defaultInstallProvider, beginOwnerUpdate = beginServiceOwnerUpdate,
+  writeEnvironment = writeServiceEnvironment, deferOwnerCommit = false } = {}) {
   const spec = serviceSpec({ workspace, stateRoot, entryScript });
-  const serviceEnvironment = writeServiceEnvironment(spec.stateRoot);
+  const ownerUpdate = beginOwnerUpdate({ ...spec, version });
+  let serviceEnvironment;
+  try { serviceEnvironment = writeEnvironment(spec.stateRoot); }
+  catch (error) {
+    try { ownerUpdate.rollback(); }
+    catch (rollbackError) {
+      throw new AggregateError([error, rollbackError],
+        "service environment preparation failed and the previous machine service owner could not be restored");
+    }
+    throw error;
+  }
   let result;
-  if (process.platform === "darwin") result = await installLaunchd(spec, logger);
-  else if (process.platform === "win32") result = await installWindowsTask(spec, logger, { run: serviceRun });
-  else result = await installSystemd(spec, logger);
-  return { ...result, service_environment: serviceEnvironment };
+  try { result = await installProvider(spec, logger); }
+  catch (error) {
+    throw new Error(
+      "autostart installation threw after its machine service owner became pending; service start is blocked until reinstall",
+      { cause: error },
+    );
+  }
+  if (result?.ok !== true) {
+    return withDeferredOwnerTransaction({
+      ...result,
+      service_environment: serviceEnvironment,
+      service_owner: { status: "pending", version },
+      reason: result?.reason || "installation_failed_owner_pending",
+    }, ownerUpdate, deferOwnerCommit);
+  }
+  if (deferOwnerCommit) {
+    return withDeferredOwnerTransaction({
+      ...result,
+      service_environment: serviceEnvironment,
+      service_owner: { status: "pending", version },
+    }, ownerUpdate, true);
+  }
+  let owner;
+  try { owner = ownerUpdate.commit(); }
+  catch (error) {
+    throw new Error(
+      "autostart definition was installed but its machine service owner could not be committed; the pending owner was retained and service start is blocked until reinstall",
+      { cause: error },
+    );
+  }
+  return { ...result, service_environment: serviceEnvironment, service_owner: { status: owner.status, version: owner.version } };
 }
 
+function withDeferredOwnerTransaction(result, ownerUpdate, enabled) {
+  if (!enabled) return result;
+  if (!ownerUpdate?.owner || ownerUpdate.owner.status !== "pending"
+      || typeof ownerUpdate.commit !== "function" || typeof ownerUpdate.rollback !== "function") {
+    throw new Error("deferred machine service owner transaction is unavailable");
+  }
+  Object.defineProperty(result, "serviceOwnerTransaction", {
+    value: Object.freeze({
+      owner: ownerUpdate.owner,
+      commit: () => ownerUpdate.commit(),
+      rollback: () => ownerUpdate.rollback(),
+    }),
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return result;
+}
+
+async function defaultInstallProvider(spec, logger) {
+  if (process.platform === "darwin") return installLaunchd(spec, logger);
+  if (process.platform === "win32") return installWindowsTask(spec, logger, { run: serviceRun });
+  return installSystemd(spec, logger);
+}
+
+
 export async function uninstallAutostart({ stateRoot, logger = console } = {}) {
-  if (process.platform === "darwin") return uninstallLaunchd(logger);
-  if (process.platform === "win32") return uninstallWindowsTask(logger, { run: serviceRun, stateRoot });
-  return uninstallSystemd(logger);
+  let result;
+  if (process.platform === "darwin") result = await uninstallLaunchd(logger);
+  else if (process.platform === "win32") result = await uninstallWindowsTask(logger, { run: serviceRun, stateRoot });
+  else result = await uninstallSystemd(logger);
+  if (result?.ok === true) removeServiceOwner();
+  return result;
 }
 
 export async function autostartStatus() {
@@ -57,25 +133,19 @@ export async function autostartStatus() {
 export async function startAutostart({ logger = console } = {}) {
   if (process.platform === "darwin") return startLaunchd(logger);
   if (process.platform === "win32") return startWindowsTask(logger, { run: serviceRun });
-  return normalizeServiceCommandResult("systemd", await serviceRun("systemctl", ["--user", "start", "machine-bridge-mcp.service"]));
+  return startSystemd(logger);
 }
 
-export async function stopAutostart({ logger = console } = {}) {
-  if (process.platform === "darwin") return stopLaunchd(logger);
-  if (process.platform === "win32") return stopWindowsTask(logger, { run: serviceRun });
-  return normalizeServiceCommandResult("systemd", await serviceRun("systemctl", ["--user", "stop", "machine-bridge-mcp.service"]), { allowAlreadyStopped: true });
+export async function restartAutostart({ logger = console } = {}) {
+  if (process.platform === "darwin") return restartLaunchd(logger);
+  if (process.platform === "win32") return restartWindowsTask(logger, { run: serviceRun });
+  return restartSystemd(logger);
 }
 
-export function normalizeServiceCommandResult(provider, result, { allowAlreadyStopped = false } = {}) {
-  const detail = `${result?.stdout || ""}
-${result?.stderr || ""}`;
-  const alreadyStopped = allowAlreadyStopped && /(?:not loaded|not found|does not exist|cannot find|not running|inactive)/i.test(detail);
-  return {
-    ...result,
-    ok: result?.code === 0 || alreadyStopped,
-    provider,
-    already_stopped: alreadyStopped,
-  };
+export async function stopAutostart({ logger = console } = {}) {
+  if (process.platform === "darwin") return stopLaunchdService(logger);
+  if (process.platform === "win32") return stopWindowsTask(logger, { run: serviceRun });
+  return stopSystemdService(logger);
 }
 
 export function trimAutostartLogs(stateRoot, options = {}) {
@@ -84,37 +154,43 @@ export function trimAutostartLogs(stateRoot, options = {}) {
   const keepBytes = Math.min(maxBytes, Number.isFinite(Number(options.keepBytes)) ? Math.max(1024, Number(options.keepBytes)) : 1024 * 1024);
   const schemaVersion = String(AUTOSTART_LOG_SCHEMA_VERSION);
   const logs = path.join(root, "logs");
+  ensureOwnerOnlyDir(logs);
   const schemaFile = path.join(logs, ".log-schema");
   const reset = readLogSchema(schemaFile) !== schemaVersion;
-
-  for (const name of ["daemon.out.log", "daemon.err.log"]) {
-    const file = path.join(logs, name);
-    let fd;
-    try {
-      const opened = openRegularFileSync(file, fsConstants.O_RDWR, {
-        label: "autostart log path",
-        chmod: 0o600,
-      });
-      fd = opened.fd;
+  const openedLogs = [];
+  try {
+    for (const name of ["daemon.out.log", "daemon.err.log"]) {
+      const file = path.join(logs, name);
+      ensurePrivateLogFile(file);
+      openedLogs.push(openRegularFileSync(file, fsConstants.O_RDWR, {
+        label: "autostart log path", chmod: 0o600, rejectMultipleLinks: true,
+      }));
+    }
+    for (const opened of openedLogs) {
       if (reset) {
-        ftruncateSync(fd, 0);
+        ftruncateSync(opened.fd, 0);
       } else if (opened.info.size > maxBytes) {
-        const tail = readLogTail(fd, opened.info.size, keepBytes);
-        ftruncateSync(fd, 0);
-        if (tail.length) writeSync(fd, tail, 0, tail.length, 0);
+        const tail = readLogTail(opened.fd, opened.info.size, keepBytes);
+        ftruncateSync(opened.fd, 0);
+        if (tail.length) writeSync(opened.fd, tail, 0, tail.length, 0);
       }
-    } catch {
-      // Log maintenance is best effort and must not stop daemon startup.
-    } finally {
-      if (fd !== undefined) try { closeSync(fd); } catch {}
+    }
+    writePrivateServiceFile(schemaFile, `${schemaVersion}\n`);
+  } finally {
+    for (const opened of openedLogs) {
+      try { closeSync(opened.fd); }
+      catch { /* Descriptor cleanup cannot improve the already-completed log rotation outcome. */ }
     }
   }
-
-  try { writePrivateServiceFile(schemaFile, `${schemaVersion}\n`); } catch {}
 }
 
 function readLogSchema(file) {
-  try { return readBoundedRegularFileSync(file, 64).toString("utf8").trim(); } catch { return ""; }
+  try {
+    return readBoundedRegularFileSync(file, 64, "autostart log schema", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    }).toString("utf8").trim();
+  } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
 }
 
 function readLogTail(fd, size, limit) {
@@ -172,33 +248,37 @@ export function stableNodeExecutable(options = {}) {
       if (!sameExecutable) continue;
       if (platform !== "win32" && (statSync(candidate).mode & 0o111) === 0) continue;
       return candidate;
-    } catch {}
+    } catch { /* Inaccessible or transient PATH candidates are skipped in favor of the known executable. */ }
   }
   return execPath;
 }
 
 export function serviceEnvironmentPath(options = {}) {
   const platform = String(options.platform || process.platform);
+  const pathApi = platform === "win32" ? path.win32 : path;
   const delimiter = String(options.delimiter || (platform === "win32" ? ";" : ":"));
   const pathEnv = String(options.pathEnv ?? process.env.PATH ?? "");
   const node = String(options.node || process.execPath || "");
   const entryScript = String(options.entryScript || "");
+  const entryDirectory = entryScript ? pathApi.dirname(pathApi.resolve(entryScript)) : "";
   const defaults = platform === "darwin"
     ? ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"]
     : platform === "win32"
       ? []
       : ["/usr/local/bin", "/usr/bin", "/bin", "/usr/local/sbin", "/usr/sbin", "/sbin"];
+  const inheritedEntries = stripNpmLifecyclePathPrefix(pathEnv.split(delimiter));
   const candidates = [
-    node ? path.dirname(path.resolve(node)) : "",
-    entryScript ? path.dirname(path.resolve(entryScript)) : "",
-    ...pathEnv.split(delimiter),
+    node ? pathApi.dirname(pathApi.resolve(node)) : "",
+    entryDirectory,
+    ...inheritedEntries,
     ...defaults,
   ];
   const seen = new Set();
   const entries = [];
   for (const raw of candidates) {
-    if (!raw || !path.isAbsolute(raw)) continue;
-    const normalized = path.resolve(raw);
+    if (!raw || !pathApi.isAbsolute(raw)) continue;
+    const normalized = pathApi.resolve(raw);
+    if (isInactiveCandidateRuntimePath(normalized, entryDirectory, platform)) continue;
     const key = platform === "win32" ? normalized.toLowerCase() : normalized;
     if (seen.has(key)) continue;
     seen.add(key);
@@ -207,6 +287,33 @@ export function serviceEnvironmentPath(options = {}) {
   return entries.join(delimiter);
 }
 
+function stripNpmLifecyclePathPrefix(entries) {
+  let lastMarker = -1;
+  for (let index = 0; index < entries.length; index += 1) {
+    const portable = String(entries[index] || "").replaceAll("\\", "/").toLowerCase();
+    if (portable.endsWith("/node-gyp-bin") && portable.includes("/@npmcli/run-script/")) lastMarker = index;
+  }
+  return lastMarker >= 0 ? entries.slice(lastMarker + 1) : entries;
+}
+
+function isInactiveCandidateRuntimePath(candidate, entryDirectory, platform) {
+  if (!entryDirectory) return false;
+  const pathApi = platform === "win32" ? path.win32 : path;
+  const normalize = (value) => {
+    const resolved = pathApi.resolve(value);
+    return platform === "win32" ? resolved.toLowerCase() : resolved;
+  };
+  const current = normalize(entryDirectory);
+  const portable = current.replaceAll("\\", "/");
+  const marker = "/release-channels/runtimes/";
+  const markerIndex = portable.indexOf(marker);
+  if (markerIndex < 0) return false;
+  const runtimeContainer = portable.slice(0, markerIndex + marker.length - 1);
+  const normalizedCandidate = normalize(candidate).replaceAll("\\", "/");
+  return normalizedCandidate !== portable
+    && (normalizedCandidate === runtimeContainer || normalizedCandidate.startsWith(`${runtimeContainer}/`));
+}
+
 export function daemonArgs(spec) {
   return [
     spec.entryScript,
@@ -223,7 +330,7 @@ function ensurePrivateLogFile(file) {
   const opened = openRegularFileSync(
     file,
     Number(fsConstants.O_WRONLY) | Number(fsConstants.O_CREAT) | Number(fsConstants.O_APPEND),
-    { label: "autostart log path", mode: 0o600, chmod: 0o600 },
+    { label: "autostart log path", mode: 0o600, chmod: 0o600, rejectMultipleLinks: true },
   );
   closeSync(opened.fd);
 }
@@ -260,31 +367,94 @@ async function installLaunchd(spec, logger) {
 
 async function startLaunchd(logger) {
   const plistPath = launchdPlistPath();
-  const target = launchdDomainTarget();
-  if (!existsSync(plistPath)) return { ok: false, error: "launchd plist not installed" };
-  const stopped = await stopLaunchd({ info() {}, warn() {} });
-  if (!stopped.ok) return { ok: false, provider: "launchd", stop: stopped };
-  const boot = await serviceRun("launchctl", ["bootstrap", target, plistPath]);
-  const kick = await serviceRun("launchctl", ["kickstart", "-k", `${target}/${LABEL}`]);
-  const ok = boot.code === 0 || kick.code === 0;
+  const domainTarget = launchdDomainTarget();
+  const serviceTarget = launchdServiceTarget();
+  if (!existsSync(plistPath)) return { ok: false, provider: "launchd", installed: false, loaded: false, active: false, reason: "not_installed" };
+  const before = await statusLaunchd();
+  if (before.status_available !== true || typeof before.active !== "boolean") {
+    return { ok: false, provider: "launchd", installed: true, loaded: null, active: null, reason: "status_unavailable", status: before };
+  }
+  if (before.active) {
+    const existing = await waitForStableActiveStatus(statusLaunchd);
+    if (existing.stable) {
+      logger.info?.("launchd service is already running");
+      return { ...existing.status, ok: true, active_before: true, already_running: true, reason: "already_running" };
+    }
+  }
+  const boot = before.loaded
+    ? { code: 0, stdout: "", stderr: "", already_loaded: true }
+    : await serviceRun("launchctl", ["bootstrap", domainTarget, plistPath]);
+  const kick = await serviceRun("launchctl", ["kickstart", serviceTarget]);
+  const stability = await waitForStableActiveStatus(statusLaunchd);
+  const after = stability.status;
+  const ok = stability.stable;
   if (ok) logger.info?.("launchd service started");
   else logger.warn?.("launchd service failed to start");
-  return { ok, provider: "launchd", bootstrap: boot, kickstart: kick };
+  return {
+    ok,
+    provider: "launchd",
+    installed: true,
+    loaded: after?.loaded === true,
+    active_before: false,
+    active: after?.active === true,
+    bootstrap: boot,
+    kickstart: kick,
+  };
 }
 
-async function stopLaunchd(logger) {
+async function restartLaunchd(logger) {
   const plistPath = launchdPlistPath();
-  const domainTarget = launchdDomainTarget();
-  const serviceTarget = launchdServiceTarget();
+  if (!existsSync(plistPath)) return { ok: false, provider: "launchd", installed: false, reason: "not_installed" };
   const before = await statusLaunchd();
+  if (before.status_available !== true || typeof before.active !== "boolean") {
+    return { ok: false, provider: "launchd", installed: true, active: null, restarted: false, reason: "status_unavailable", status: before };
+  }
   if (!before.active) {
+    const started = await startLaunchd(logger);
+    return { ...started, restarted: false, reason: started.ok ? "started_inactive_service" : started.reason || "start_failed" };
+  }
+  const target = launchdServiceTarget();
+  const previousPid = before.pid;
+  const kick = await serviceRun("launchctl", ["kickstart", "-k", target]);
+  const changed = await waitForStatus(
+    statusLaunchd,
+    (status) => status?.active === true && (!previousPid || status.pid !== previousPid),
+  );
+  const stability = changed?.active === true && (!previousPid || changed.pid !== previousPid)
+    ? await waitForStableActiveStatus(statusLaunchd, { identity: (status) => status?.pid || null })
+    : { stable: false, status: changed };
+  const after = stability.status;
+  const ok = kick.code === 0 && stability.stable && (!previousPid || after?.pid !== previousPid);
+  if (ok) logger.info?.("launchd service restarted");
+  else logger.warn?.("launchd service restart could not be verified");
+  return { ok, provider: "launchd", installed: true, active_before: true, active: after?.active === true && stability.stable, restarted: ok, kickstart: kick };
+}
+
+export async function stopLaunchdService(logger = console, options = {}) {
+  const plistPath = launchdPlistPath();
+  const run = typeof options.run === "function" ? options.run : serviceRun;
+  const readStatus = typeof options.readStatus === "function" ? options.readStatus : statusLaunchd;
+  const waitForUnloaded = typeof options.waitForUnloaded === "function"
+    ? options.waitForUnloaded
+    : callback => waitForStatus(callback, launchdStatusIsSafelyUnloaded, { attempts: 100, delayMs: 100 });
+  const before = await readStatus();
+  if (!before.loaded) {
+    if (!launchdStatusIsSafelyUnloaded(before)) {
+      return {
+        ok: false, provider: "launchd", installed: before?.installed === true, loaded: null,
+        active_before: null, active: null, restore_required: null, already_stopped: false,
+        reason: "status_unavailable", status: before,
+      };
+    }
     logger.info?.("launchd service is not loaded");
     return {
       ok: true,
       provider: "launchd",
-      installed: existsSync(plistPath),
+      installed: before?.installed === true,
+      loaded: false,
       active_before: false,
       active: false,
+      restore_required: false,
       already_stopped: true,
       code: 0,
       stdout: "",
@@ -292,44 +462,61 @@ async function stopLaunchd(logger) {
     };
   }
 
-  const byServiceTarget = await serviceRun("launchctl", ["bootout", serviceTarget]);
+  const uid = options.uid === undefined ? process.getuid?.() : options.uid;
+  const domainTarget = launchdDomainTarget(uid);
+  const serviceTarget = launchdServiceTarget(uid);
+  const byServiceTarget = await run("launchctl", ["bootout", serviceTarget]);
   const byPlist = byServiceTarget.code === 0
     ? null
-    : await serviceRun("launchctl", ["bootout", domainTarget, plistPath]);
-  const after = await waitForInactiveStatus(statusLaunchd);
+    : await run("launchctl", ["bootout", domainTarget, plistPath]);
+  const after = await waitForUnloaded(readStatus);
   const rawResult = byPlist || byServiceTarget;
-  const active = after?.active !== false;
-  const ok = !active;
+  const ok = launchdStatusIsSafelyUnloaded(after);
   if (ok) logger.info?.("launchd service stopped");
-  else logger.warn?.("launchd service is still active after the stop request");
+  else logger.warn?.("launchd service removal from the launchd domain could not be verified");
   return {
     ...rawResult,
     ok,
     provider: "launchd",
-    installed: existsSync(plistPath),
-    active_before: true,
-    active,
+    installed: after?.installed === true,
+    loaded: ok ? false : after?.loaded ?? null,
+    active_before: before.active === true,
+    active: ok ? false : after?.active ?? null,
+    // Once bootout is dispatched, an initially active service may still
+    // disappear after this observation window. Preserve rollback intent even
+    // when stop settlement itself is inconclusive.
+    restore_required: before.active === true,
+    mutation_attempted: true,
     already_stopped: false,
     code: ok ? 0 : rawResult.code,
+    reason: ok ? "stopped" : "stop_not_observed",
+    status: after,
     bootout_service_target: byServiceTarget,
     ...(byPlist ? { bootout_plist_fallback: byPlist } : {}),
   };
 }
 
+function launchdStatusIsSafelyUnloaded(status) {
+  return status?.status_available === true && status?.loaded === false && status?.active === false;
+}
+
 async function uninstallLaunchd(logger) {
-  const stopped = await stopLaunchd(logger);
   const plistPath = launchdPlistPath();
+  const definitionIdentity = snapshotServiceDefinition(plistPath, "launchd service definition");
+  const stopped = await stopLaunchdService(logger);
   if (!stopped.ok) return { ok: false, provider: "launchd", path: plistPath, stop: stopped };
-  if (existsSync(plistPath)) rmSync(plistPath, { force: true });
+  if (!removeServiceDefinitionIfCurrent(plistPath, definitionIdentity, "launchd service definition")) {
+    logger.warn?.("launchd service definition changed during removal; the replacement was retained.");
+    return { ok: false, provider: "launchd", path: plistPath, stop: stopped, reason: "definition_changed" };
+  }
   logger.info?.("Autostart removed.");
   return { ok: true, provider: "launchd", path: plistPath, stop: stopped };
 }
 
 async function statusLaunchd() {
   const plistPath = launchdPlistPath();
-  const target = launchdServiceTarget();
-  const result = await serviceRun("launchctl", ["print", target]);
-  return { ok: existsSync(plistPath), provider: "launchd", installed: existsSync(plistPath), path: plistPath, active: result.code === 0, detail: result.stdout || result.stderr };
+  const result = await serviceRun("launchctl", ["print", launchdServiceTarget()]);
+  return launchdStatusSummary({ installed: existsSync(plistPath), definition: LABEL, result });
 }
 
 export function launchdPlist({ args, pathEnv, stdout, stderr }) {
@@ -377,26 +564,132 @@ async function installSystemd(spec, logger) {
 
 async function uninstallSystemd(logger) {
   const servicePath = systemdPath();
+  const definitionIdentity = snapshotServiceDefinition(servicePath, "systemd service definition");
+  const definitionPresent = definitionIdentity !== null;
   const disable = await serviceRun("systemctl", ["--user", "disable", "--now", "machine-bridge-mcp.service"]);
   const activeCheck = await serviceRun("systemctl", ["--user", "is-active", "machine-bridge-mcp.service"]);
-  const active = activeCheck.code === 0;
-  if (active) {
-    logger.warn?.("systemd service is still active; its definition was not removed.");
-    return { ok: false, provider: "systemd", path: servicePath, disable, active_check: activeCheck, active: true };
+  const status = systemdStatusSummary({ installed: definitionPresent, definition: "machine-bridge-mcp.service", result: activeCheck });
+  const decision = systemdRemovalDecision({ definitionPresent, disableCode: disable.code, status });
+  if (!decision.removable) {
+    logger.warn?.("systemd service removal could not be verified; its definition was not removed.");
+    return { ok: false, provider: "systemd", path: servicePath, disable, active_check: activeCheck, status, active: status.active, reason: decision.reason };
+  }
+  if (!removeServiceDefinitionIfCurrent(servicePath, definitionIdentity, "systemd service definition")) {
+    logger.warn?.("systemd service definition changed during removal; the replacement was retained.");
+    return { ok: false, provider: "systemd", path: servicePath, disable, active_check: activeCheck, status, active: false, reason: "definition_changed" };
   }
-  if (existsSync(servicePath)) rmSync(servicePath, { force: true });
   const reload = await serviceRun("systemctl", ["--user", "daemon-reload"]);
-  const ok = reload.code === 0 && (disable.code === 0 || /not loaded|not found|does not exist/i.test(`${disable.stdout}
-${disable.stderr}`));
+  const ok = reload.code === 0;
   if (ok) logger.info?.("Autostart removed.");
   else logger.warn?.("Autostart removal reported an error.");
-  return { ok, provider: "systemd", path: servicePath, disable, active_check: activeCheck, reload, active: false };
+  return { ok, provider: "systemd", path: servicePath, disable, active_check: activeCheck, status, reload, active: false, already_absent: decision.alreadyAbsent, reason: ok ? decision.reason : "reload_failed" };
+}
+
+export async function stopSystemdService(logger = console, options = {}) {
+  const run = typeof options.run === "function" ? options.run : serviceRun;
+  const readStatus = typeof options.readStatus === "function" ? options.readStatus : statusSystemd;
+  const waitForInactive = typeof options.waitForInactive === "function"
+    ? options.waitForInactive
+    : callback => waitForInactiveStatus(callback);
+  const before = await readStatus();
+  if (systemdStatusIsInactive(before)) {
+    logger.info?.("systemd service is not active");
+    return {
+      ok: true,
+      provider: "systemd",
+      installed: before?.installed === true,
+      active_before: false,
+      active: false,
+      restore_required: false,
+      already_stopped: true,
+      state: before?.state || "inactive",
+    };
+  }
+  if (before?.active !== true && ["unknown", "maintenance"].includes(before?.state)) {
+    return {
+      ok: false,
+      provider: "systemd",
+      installed: before?.installed === true,
+      active_before: null,
+      active: null,
+      restore_required: null,
+      reason: "status_unavailable",
+      status: before,
+    };
+  }
+  const command = await run("systemctl", ["--user", "stop", "machine-bridge-mcp.service"]);
+  const after = await waitForInactive(readStatus);
+  const inactive = systemdStatusIsInactive(after);
+  if (inactive) logger.info?.("systemd service stopped");
+  else logger.warn?.("systemd service stop could not be verified");
+  return {
+    ok: inactive,
+    provider: "systemd",
+    installed: after?.installed === true,
+    active_before: before?.active === true,
+    active: inactive ? false : after?.active ?? null,
+    restore_required: inactive && systemdStatusRequiresRestore(before),
+    already_stopped: false,
+    command,
+    status: after,
+    reason: inactive ? "stopped" : "stop_not_observed",
+  };
+}
+
+function systemdStatusIsInactive(status) {
+  if (status?.active !== false) return false;
+  if (["inactive", "failed"].includes(status?.state)) return true;
+  return status?.installed === false && status?.state === "unknown";
+}
+function systemdStatusRequiresRestore(status) {
+  return status?.active === true || ["activating", "reloading"].includes(status?.state);
+}
+
+async function startSystemd(logger) {
+  const before = await statusSystemd();
+  if (typeof before.active !== "boolean") {
+    return { ok: false, provider: "systemd", installed: before.installed === true, active: null, reason: "status_unavailable", status: before };
+  }
+  if (before.installed !== true) {
+    return { ok: false, provider: "systemd", installed: false, active: false, reason: "not_installed", status: before };
+  }
+  if (before.active) {
+    const existing = await waitForStableActiveStatus(statusSystemd);
+    if (existing.stable) {
+      logger.info?.("systemd service is already running");
+      return { ...existing.status, ok: true, active_before: true, already_running: true, reason: "already_running" };
+    }
+  }
+  const command = await serviceRun("systemctl", ["--user", "start", "machine-bridge-mcp.service"]);
+  const stability = await waitForStableActiveStatus(statusSystemd);
+  const after = stability.status;
+  const ok = command.code === 0 && stability.stable;
+  if (ok) logger.info?.("systemd service started");
+  else logger.warn?.("systemd service failed to start");
+  return { ok, provider: "systemd", installed: after.installed, active_before: false, active: after.active, command };
+}
+
+async function restartSystemd(logger) {
+  const before = await statusSystemd();
+  if (typeof before.active !== "boolean") {
+    return { ok: false, provider: "systemd", installed: before.installed === true, active: null, restarted: false, reason: "status_unavailable", status: before };
+  }
+  if (before.installed !== true) {
+    return { ok: false, provider: "systemd", installed: false, active: false, restarted: false, reason: "not_installed", status: before };
+  }
+  const command = await serviceRun("systemctl", ["--user", "restart", "machine-bridge-mcp.service"]);
+  const stability = await waitForStableActiveStatus(statusSystemd);
+  const after = stability.status;
+  const ok = command.code === 0 && stability.stable;
+  if (ok) logger.info?.("systemd service restarted");
+  else logger.warn?.("systemd service restart could not be verified");
+  return { ok, provider: "systemd", installed: after.installed, active: after.active, restarted: ok, command };
 }
 
 async function statusSystemd() {
   const servicePath = systemdPath();
-  const result = await serviceRun("systemctl", ["--user", "status", "machine-bridge-mcp.service", "--no-pager"]);
-  return { ok: existsSync(servicePath), provider: "systemd", installed: existsSync(servicePath), path: servicePath, active: result.code === 0, detail: result.stdout || result.stderr };
+  const result = await serviceRun("systemctl", ["--user", "is-active", "machine-bridge-mcp.service"]);
+  return systemdStatusSummary({ installed: existsSync(servicePath), definition: "machine-bridge-mcp.service", result });
 }
 
 export function systemdUnit(spec) {