machine-bridge-mcp 3.0.0-beta.21 → 3.0.0-beta.26

package/src/local/service-convergence.mjs

@@ -8,6 +8,39 @@ export async function waitForActiveStatus(
   return waitForStatus(readStatus, (status) => status?.active === true, { attempts, delayMs, sleep });
 }
 
+
+export async function waitForStableActiveStatus(
+  readStatus,
+  { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, stableSamples = 5, sleep = delay, identity = stableIdentity } = {},
+) {
+  if (typeof readStatus !== "function") throw new TypeError("readStatus must be a function");
+  if (typeof identity !== "function") throw new TypeError("identity must be a function");
+  const maximum = Number.isInteger(attempts) && attempts > 0 ? attempts : DEFAULT_ATTEMPTS;
+  const required = Number.isInteger(stableSamples) && stableSamples > 0 ? stableSamples : 5;
+  let status = null;
+  let consecutive = 0;
+  let priorIdentity = null;
+  for (let attempt = 1; attempt <= maximum; attempt += 1) {
+    status = await readStatus();
+    const currentIdentity = status?.active === true ? identity(status) : null;
+    const identityChanged = consecutive > 0
+      && (priorIdentity !== null || currentIdentity !== null)
+      && currentIdentity !== priorIdentity;
+    if (status?.active === true && !identityChanged) consecutive += 1;
+    else consecutive = status?.active === true ? 1 : 0;
+    priorIdentity = currentIdentity;
+    if (consecutive >= required) return { stable: true, status, samples: consecutive, attempts: attempt };
+    if (attempt < maximum) await sleep(delayMs);
+  }
+  return { stable: false, status, samples: consecutive, attempts: maximum };
+}
+
+function stableIdentity(status) {
+  if (Number.isInteger(status?.pid) && status.pid > 0) return `pid:${status.pid}`;
+  if (typeof status?.last_run_time === "string" && status.last_run_time) return `run:${status.last_run_time}`;
+  return null;
+}
+
 export async function waitForInactiveStatus(
   readStatus,
   { attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, sleep = delay } = {},

package/src/local/service-owner.mjs

@@ -0,0 +1,147 @@
+// @ts-check
+
+import { randomBytes } from "node:crypto";
+import { existsSync, realpathSync, rmSync, statSync } from "node:fs";
+import path from "node:path";
+import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { ensureOwnerOnlyDir, machineServiceControlRoot } from "./state.mjs";
+
+const SCHEMA_VERSION = 1;
+const MAX_BYTES = 64 * 1024;
+const FILE_NAME = "service-owner.json";
+const VERSION = /^[0-9A-Za-z.+_-]{1,64}$/;
+const TRANSACTION = /^[A-Za-z0-9_-]{20,128}$/;
+
+/** @typedef {{ schemaVersion: 1, status: "pending" | "committed", transactionId: string, workspace: string, stateRoot: string, entryScript: string, version: string, createdAt: string, committedAt: string | null }} ServiceOwner */
+/** @typedef {{ workspace?: unknown, stateRoot?: unknown, entryScript?: unknown, version?: unknown }} ServiceOwnerSpec */
+/** @typedef {{ controlRoot?: string }} ServiceOwnerOptions */
+
+/** @param {ServiceOwnerOptions} [options] */ export function serviceOwnerPath(options = {}) {
+  return path.join(machineServiceControlRoot(options), FILE_NAME);
+}
+
+/** @param {ServiceOwnerSpec} spec @param {ServiceOwnerOptions} [options] */ export function beginServiceOwnerUpdate(spec, options = {}) {
+  const file = serviceOwnerPath(options);
+  ensureOwnerOnlyDir(path.dirname(file));
+  const previous = existsSync(file) ? readOwnerSnapshot(file) : null;
+  const transactionId = randomBytes(24).toString("base64url");
+  const createdAt = new Date().toISOString();
+  const pending = normalizeOwner({
+    schemaVersion: SCHEMA_VERSION,
+    status: "pending",
+    transactionId,
+    workspace: spec?.workspace,
+    stateRoot: spec?.stateRoot,
+    entryScript: spec?.entryScript,
+    version: spec?.version,
+    createdAt,
+    committedAt: null,
+  });
+  writeOwner(file, pending);
+  let closed = false;
+  return {
+    path: file,
+    owner: pending,
+    commit() {
+      if (closed) throw new Error("service owner transaction is already closed");
+      assertCurrentTransaction(file, transactionId, "pending");
+      const committed = normalizeOwner({ ...pending, status: "committed", committedAt: new Date().toISOString() });
+      writeOwner(file, committed);
+      closed = true;
+      return committed;
+    },
+    rollback() {
+      if (closed) return false;
+      assertCurrentTransaction(file, transactionId, "pending");
+      if (previous) replaceFileAtomicallySync(file, previous.raw, { mode: 0o600 });
+      else rmSync(file, { force: true });
+      closed = true;
+      return true;
+    },
+  };
+}
+
+/** @param {ServiceOwnerOptions} [options] @returns {ServiceOwner | null} */ export function loadServiceOwner(options = {}) {
+  const file = serviceOwnerPath(options);
+  return existsSync(file) ? readOwnerSnapshot(file).owner : null;
+}
+
+/** @param {ServiceOwnerOptions} [options] @returns {ServiceOwner | null} */ export function loadCommittedServiceOwner(options = {}) {
+  const owner = loadServiceOwner(options);
+  if (!owner) return null;
+  if (owner.status !== "committed") {
+    throw new Error("machine service owner transition is incomplete; reinstall the service before starting it");
+  }
+  return owner;
+}
+
+/** @param {ServiceOwnerOptions} [options] */ export function removeServiceOwner(options = {}) {
+  const file = serviceOwnerPath(options);
+  if (!existsSync(file)) return false;
+  readBoundedRegularFileSync(file, MAX_BYTES, "machine service owner file", {
+    verifyPathIdentity: true, rejectMultipleLinks: true,
+  });
+  rmSync(file, { force: true });
+  return true;
+}
+
+/** @param {string} file @returns {{ owner: ServiceOwner, raw: Buffer }} */ function readOwnerSnapshot(file) {
+  const raw = readBoundedRegularFileSync(file, MAX_BYTES, "machine service owner file");
+  let parsed;
+  try { parsed = JSON.parse(raw.toString("utf8")); }
+  catch (error) { throw new Error("machine service owner file is not valid JSON", { cause: error }); }
+  return { owner: normalizeOwner(parsed), raw };
+}
+
+/** @param {string} file @param {ServiceOwner} owner */ function writeOwner(file, owner) {
+  const content = `${JSON.stringify(owner, null, 2)}\n`;
+  if (Buffer.byteLength(content) > MAX_BYTES) throw new Error("machine service owner record exceeds the size limit");
+  replaceFileAtomicallySync(file, content, { mode: 0o600 });
+}
+
+/** @param {string} file @param {string} transactionId @param {"pending" | "committed"} status */ function assertCurrentTransaction(file, transactionId, status) {
+  const current = readOwnerSnapshot(file).owner;
+  if (current.transactionId !== transactionId || current.status !== status) {
+    throw new Error("machine service owner transaction changed before completion");
+  }
+}
+
+/** @param {unknown} value @returns {ServiceOwner} */ function normalizeOwner(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("machine service owner must be an object");
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (record.schemaVersion !== SCHEMA_VERSION) throw new Error("machine service owner schema is unsupported");
+  if (record.status !== "pending" && record.status !== "committed") throw new Error("machine service owner status is invalid");
+  if (typeof record.transactionId !== "string" || !TRANSACTION.test(record.transactionId)) throw new Error("machine service owner transaction id is invalid");
+  if (typeof record.version !== "string" || !VERSION.test(record.version)) throw new Error("machine service owner version is invalid");
+  const workspace = canonicalDirectory(record.workspace, "workspace");
+  const stateRoot = canonicalDirectory(record.stateRoot, "state root");
+  const entryScript = canonicalFile(record.entryScript, "entry script");
+  const createdAt = isoTimestamp(record.createdAt, "createdAt");
+  const committedAt = record.status === "committed" ? isoTimestamp(record.committedAt, "committedAt") : null;
+  return { schemaVersion: SCHEMA_VERSION, status: record.status, transactionId: record.transactionId,
+    workspace, stateRoot, entryScript, version: record.version, createdAt, committedAt };
+}
+
+/** @param {unknown} value @param {string} label */ function canonicalDirectory(value, label) {
+  const canonical = canonicalPath(value, label);
+  if (!statSync(canonical).isDirectory()) throw new Error(`machine service owner ${label} is not a directory`);
+  return canonical;
+}
+
+/** @param {unknown} value @param {string} label */ function canonicalFile(value, label) {
+  const canonical = canonicalPath(value, label);
+  if (!statSync(canonical).isFile()) throw new Error(`machine service owner ${label} is not a file`);
+  return canonical;
+}
+
+/** @param {unknown} value @param {string} label */ function canonicalPath(value, label) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) throw new Error(`machine service owner ${label} must be absolute`);
+  try { return realpathSync.native ? realpathSync.native(value) : realpathSync(value); }
+  catch (error) { throw new Error(`machine service owner ${label} is unavailable`, { cause: error }); }
+}
+
+/** @param {unknown} value @param {string} label */ function isoTimestamp(value, label) {
+  if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) throw new Error(`machine service owner ${label} is invalid`);
+  return value;
+}

package/src/local/service-restart-handoff.mjs

@@ -1,24 +1,38 @@
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { restartAutostart } from "./service.mjs";
+import { restartOwnedServiceRuntime } from "./service-runtime.mjs";
 import { createLogger } from "./log.mjs";
+import { acquireMachineServiceLockWithWait } from "./state.mjs";
 
 const DEFAULT_DELAY_MS = 300;
 const MAX_DELAY_MS = 5_000;
 
 export async function runServiceRestartHandoff(options = {}) {
   const delayMs = boundedDelay(options.delayMs ?? process.argv[2]);
-  const restart = typeof options.restartAutostart === "function" ? options.restartAutostart : restartAutostart;
+  const restart = typeof options.restartServiceRuntime === "function"
+    ? options.restartServiceRuntime
+    : typeof options.restartAutostart === "function" ? options.restartAutostart : restartOwnedServiceRuntime;
   const sleep = typeof options.sleep === "function" ? options.sleep : delay;
   const logger = options.logger || createLogger({ component: "service-restart", level: "warn", format: "json", stderrOnly: true });
+  const acquireLock = typeof options.acquireServiceLock === "function"
+    ? options.acquireServiceLock
+    : () => acquireMachineServiceLockWithWait({ operation: "service-restart", logger, ...(options.serviceLockOptions || {}) });
   await sleep(delayMs);
-  const result = await restart({ logger });
-  if (result?.ok !== true) {
-    const error = new Error(`service restart handoff failed (${result?.reason || result?.provider || "unknown"})`);
-    error.result = result;
-    throw error;
+  const lock = await acquireLock();
+  if (!lock?.acquired || typeof lock.release !== "function") {
+    throw new Error("machine-service operation lock could not be acquired for restart");
+  }
+  try {
+    const result = await restart({ logger });
+    if (result?.ok !== true) {
+      const error = new Error(`service restart handoff failed (${result?.reason || result?.provider || "unknown"})`);
+      error.result = result;
+      throw error;
+    }
+    return result;
+  } finally {
+    lock.release();
   }
-  return result;
 }
 
 export async function serviceRestartHandoffMain(options = {}) {

package/src/local/service-runtime.mjs

@@ -0,0 +1,145 @@
+// @ts-check
+
+import { inspectWorkspaceDaemon } from "./daemon-process.mjs";
+import { loadCommittedServiceOwner } from "./service-owner.mjs";
+import { autostartStatus, restartAutostart, startAutostart, stopAutostart } from "./service.mjs";
+import { loadState } from "./state.mjs";
+
+/** @typedef {{ status: string, workspace: string, stateRoot: string, entryScript: string, version: string }} ServiceOwner */
+/** @typedef {Record<string, unknown> & { ok?: boolean, active?: boolean | null, provider?: string, reason?: string }} ProviderResult */
+/** @typedef {Record<string, unknown> & { alive?: boolean, verified_service_daemon?: boolean, mode?: string, startup_readiness_verified?: boolean, identity_reason?: string }} DaemonStatus */
+/** @typedef {{ expectedVersion: string, expectedEntryScript: string }} DaemonExpectation */
+/** @typedef {{ owner?: ServiceOwner, ownerOptions?: Record<string, unknown>, loadOwner?: (options: Record<string, unknown>) => ServiceOwner | null, loadState?: (workspace: string, options: { stateDir: string }) => object, inspectDaemon?: (state: object, expectation: DaemonExpectation) => DaemonStatus, readProvider?: () => ProviderResult | Promise<ProviderResult>, mutateProvider?: (options: { logger?: Console }) => ProviderResult | Promise<ProviderResult>, stopProvider?: (options: { logger?: Console }) => ProviderResult | Promise<ProviderResult>, logger?: Console, attempts?: number, delayMs?: number, sleep?: (milliseconds: number) => Promise<void> }} OwnedRuntimeOptions */
+/** @typedef {{ inspectDaemon?: () => DaemonStatus, attempts?: number, delayMs?: number, sleep?: (milliseconds: number) => Promise<void> }} OwnedWaitOptions */
+
+const DEFAULT_ATTEMPTS = 900;
+const DEFAULT_DELAY_MS = 100;
+
+/** @param {OwnedRuntimeOptions} [options] */
+export async function startOwnedServiceRuntime(options = {}) {
+  return convergeOwnedServiceRuntime({
+    ...options,
+    mutateProvider: options.mutateProvider || startAutostart,
+  });
+}
+
+/** @param {OwnedRuntimeOptions} [options] */
+export async function restartOwnedServiceRuntime(options = {}) {
+  return convergeOwnedServiceRuntime({
+    ...options,
+    mutateProvider: options.mutateProvider || restartAutostart,
+  });
+}
+
+/** @param {OwnedRuntimeOptions} [options] */
+export async function convergeOwnedServiceRuntime(options = {}) {
+  const loadOwner = options.loadOwner === undefined ? loadCommittedServiceOwner : options.loadOwner;
+  const loadOwnerState = options.loadState === undefined ? loadState : options.loadState;
+  const inspectDaemon = options.inspectDaemon === undefined ? inspectWorkspaceDaemon : options.inspectDaemon;
+  const readProvider = options.readProvider === undefined ? autostartStatus : options.readProvider;
+  const mutateProvider = options.mutateProvider;
+  const stopProvider = options.stopProvider === undefined ? stopAutostart : options.stopProvider;
+  for (const [name, value] of Object.entries({ loadOwner, loadOwnerState, inspectDaemon, readProvider, stopProvider })) {
+    if (typeof value !== "function") throw new TypeError(`owned service runtime requires ${name}`);
+  }
+  if (typeof mutateProvider !== "function") throw new TypeError("owned service runtime requires mutateProvider");
+  const owner = options.owner || loadOwner(options.ownerOptions || {});
+  if (!owner) throw new Error("machine service owner is unavailable; reinstall the service before starting it");
+  const state = loadOwnerState(owner.workspace, { stateDir: owner.stateRoot });
+  const inspect = () => inspectDaemon(state, {
+    expectedVersion: owner.version,
+    expectedEntryScript: owner.entryScript,
+  });
+  const providerBefore = await readProvider();
+  if (typeof providerBefore?.active !== "boolean") {
+    throw new Error("machine service provider activity could not be verified before mutation");
+  }
+  const daemonBefore = inspect();
+  assertStartOwnership(providerBefore, daemonBefore);
+  if (providerBefore.active === true && readyOwnedDaemon(daemonBefore)) {
+    return { ok: true, active: true, already_running: true, reason: "already_running",
+      provider: providerBefore.provider, daemon: daemonBefore, service_owner: ownerSummary(owner) };
+  }
+  const providerResult = await mutateProvider({ logger: options.logger });
+  if (providerResult?.ok !== true || providerResult.active !== true) return providerResult;
+  const convergence = await waitForOwnedServiceDaemon({
+    inspectDaemon: inspect,
+    attempts: options.attempts,
+    delayMs: options.delayMs,
+    sleep: options.sleep,
+  });
+  if (convergence.ok) {
+    return { ...providerResult, ok: true, active: true, daemon: convergence.daemon,
+      service_owner: ownerSummary(owner), readiness_attempts: convergence.attempts };
+  }
+  const providerStop = await stopProvider({ logger: options.logger });
+  const providerInactive = providerStop?.ok === true && providerStop.active === false;
+  return {
+    ok: false,
+    active: providerStop?.active === true ? true : providerStop?.active === false ? false : null,
+    provider: providerResult.provider || providerStop?.provider || "unknown",
+    reason: providerInactive ? convergence.reason : `${convergence.reason}_provider_stop_unverified`,
+    daemon: convergence.daemon,
+    provider_start: providerResult,
+    provider_stop: providerStop,
+    service_owner: ownerSummary(owner),
+  };
+}
+
+/** @param {OwnedWaitOptions} [options] */
+export async function waitForOwnedServiceDaemon(options = {}) {
+  const { inspectDaemon, attempts = DEFAULT_ATTEMPTS, delayMs = DEFAULT_DELAY_MS, sleep = delay } = options;
+  if (typeof inspectDaemon !== "function") throw new TypeError("owned service convergence requires inspectDaemon");
+  const maximum = boundedAttempts(attempts);
+  /** @type {DaemonStatus | null} */
+  let daemon = null;
+  for (let attempt = 1; attempt <= maximum; attempt += 1) {
+    daemon = inspectDaemon();
+    if (readyOwnedDaemon(daemon)) return { ok: true, attempts: attempt, daemon, reason: null };
+    if (daemon?.alive === true && daemon.verified_service_daemon !== true) {
+      return { ok: false, attempts: attempt, daemon,
+        reason: `daemon_identity_${daemon.identity_reason || "unverified"}` };
+    }
+    if (attempt < maximum) await sleep(delayMs);
+  }
+  return { ok: false, attempts: maximum, daemon,
+    reason: daemon?.alive ? "daemon_readiness_not_verified" : "daemon_not_running" };
+}
+
+/** @param {ProviderResult} provider @param {DaemonStatus} daemon */
+function assertStartOwnership(provider, daemon) {
+  if (!daemon?.alive) return;
+  if (daemon.verified_service_daemon !== true || daemon.mode !== "service") {
+    throw new Error(`refusing to mutate the machine service while its owner has a ${daemon.identity_reason || daemon.mode || "unverified"} daemon`);
+  }
+  if (provider.active !== true) {
+    throw new Error("the machine service owner has an orphaned service daemon while the provider is inactive; stop it explicitly before retrying");
+  }
+}
+
+/** @param {DaemonStatus | null | undefined} daemon */
+function readyOwnedDaemon(daemon) {
+  return daemon?.alive === true
+    && daemon.verified_service_daemon === true
+    && daemon.mode === "service"
+    && daemon.startup_readiness_verified === true;
+}
+
+/** @param {ServiceOwner} owner */
+function ownerSummary(owner) {
+  return { status: owner.status, version: owner.version };
+}
+
+/** @param {unknown} value */
+function boundedAttempts(value) {
+  const parsed = value === undefined ? DEFAULT_ATTEMPTS : Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 1800) {
+    throw new Error("owned service convergence attempts must be between 1 and 1800");
+  }
+  return parsed;
+}
+
+/** @param {number} milliseconds @returns {Promise<void>} */
+function delay(milliseconds) {
+  return new Promise(resolve => { setTimeout(resolve, milliseconds); });
+}

package/src/local/service.mjs

@@ -5,9 +5,10 @@ import { runExecutable } from "./shell.mjs";
 import { ensureOwnerOnlyDir, expandHome } from "./state.mjs";
 import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { openRegularFileSync, readBoundedRegularFileSync } from "./secure-file.mjs";
-import { waitForActiveStatus, waitForInactiveStatus, waitForStatus } from "./service-convergence.mjs";
+import { waitForInactiveStatus, waitForStableActiveStatus, waitForStatus } from "./service-convergence.mjs";
 import { launchdStatusSummary, systemdStatusSummary } from "./service-status.mjs";
 import { writeServiceEnvironment } from "./service-environment.mjs";
+import { beginServiceOwnerUpdate, removeServiceOwner } from "./service-owner.mjs";
 import {
   installWindowsTask,
   restartWindowsTask,
@@ -20,6 +21,7 @@ export { windowsCommandLineArgument } from "./windows-service.mjs";
 
 const LABEL = "dev.machine-bridge-mcp.daemon";
 const SERVICE_COMMAND_OUTPUT_BYTES = 64 * 1024;
+const SERVICE_COMMAND_TIMEOUT_MS = 30_000;
 const AUTOSTART_LOG_SCHEMA_VERSION = 4;
 
 function serviceRun(command, args) {
@@ -30,24 +32,67 @@ 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 } = {}) {
   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 {
+      ...result,
+      service_environment: serviceEnvironment,
+      service_owner: { status: "pending", version },
+      reason: result?.reason || "installation_failed_owner_pending",
+    };
+  }
+  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 } };
+}
+
+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() {
@@ -71,7 +116,7 @@ export async function restartAutostart({ logger = console } = {}) {
 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 });
+  return stopSystemdService(logger);
 }
 
 export function normalizeServiceCommandResult(provider, result, { allowAlreadyStopped = false } = {}) {
@@ -304,15 +349,19 @@ async function startLaunchd(logger) {
   if (!existsSync(plistPath)) return { ok: false, provider: "launchd", installed: false, loaded: false, active: false, reason: "not_installed" };
   const before = await statusLaunchd();
   if (before.active) {
-    logger.info?.("launchd service is already running");
-    return { ...before, ok: true, active_before: true, already_running: true, reason: "already_running" };
+    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 after = await waitForActiveStatus(statusLaunchd);
-  const ok = after?.active === true;
+  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 {
@@ -338,14 +387,18 @@ async function restartLaunchd(logger) {
   const target = launchdServiceTarget();
   const previousPid = before.pid;
   const kick = await serviceRun("launchctl", ["kickstart", "-k", target]);
-  const after = await waitForStatus(
+  const changed = await waitForStatus(
     statusLaunchd,
     (status) => status?.active === true && (!previousPid || status.pid !== previousPid),
   );
-  const ok = kick.code === 0 && after?.active === true && (!previousPid || after.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, restarted: ok, kickstart: kick };
+  return { ok, provider: "launchd", installed: true, active_before: true, active: after?.active === true && stability.stable, restarted: ok, kickstart: kick };
 }
 
 async function stopLaunchd(logger) {
@@ -362,6 +415,7 @@ async function stopLaunchd(logger) {
       loaded: false,
       active_before: false,
       active: false,
+      restore_required: false,
       already_stopped: true,
       code: 0,
       stdout: "",
@@ -384,8 +438,9 @@ async function stopLaunchd(logger) {
     ok,
     provider: "launchd",
     installed: existsSync(plistPath),
-    active_before: true,
+    active_before: before.active === true,
     active,
+    restore_required: ok,
     already_stopped: false,
     code: ok ? 0 : rawResult.code,
     bootout_service_target: byServiceTarget,
@@ -469,15 +524,77 @@ ${disable.stderr}`));
   return { ok, provider: "systemd", path: servicePath, disable, active_check: activeCheck, reload, active: false };
 }
 
+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) {
+  return status?.installed === false || status?.active === false && ["inactive", "failed"].includes(status?.state);
+}
+function systemdStatusRequiresRestore(status) {
+  return status?.active === true || ["activating", "reloading"].includes(status?.state);
+}
+
 async function startSystemd(logger) {
   const before = await statusSystemd();
   if (before.active) {
-    logger.info?.("systemd service is already running");
-    return { ...before, ok: true, active_before: true, already_running: true, reason: "already_running" };
+    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 after = await waitForActiveStatus(statusSystemd);
-  const ok = command.code === 0 && after.active === true;
+  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 };
@@ -485,8 +602,9 @@ async function startSystemd(logger) {
 
 async function restartSystemd(logger) {
   const command = await serviceRun("systemctl", ["--user", "restart", "machine-bridge-mcp.service"]);
-  const after = await waitForActiveStatus(statusSystemd);
-  const ok = command.code === 0 && after.active === true;
+  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 };