machine-bridge-mcp 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.11.1 - 2026-07-12
+
+### Reliable macOS service and orphan-daemon takeover
+
+- Stop launchd jobs by their loaded service target first, with the plist form retained as a compatibility fallback. Treat an already-unloaded job as an idempotent success, verify the post-stop state before reporting success, and prevent `service start` or `service uninstall` from continuing when the existing job remains active.
+- Detect legacy daemon locks that predate mode/version metadata by inspecting the live process command line. A process is eligible for takeover only when its PID, daemon purpose, canonical workspace, canonical state root, entrypoint, and `--daemon-only` arguments all match. Foreground or unverifiable processes are never signalled.
+- Let normal foreground startup and `machine-mcp service stop` terminate a verified detached/orphan service daemon with `SIGTERM`, wait for the actual PID as well as the lock to disappear, reclaim stale locks through the normal token-aware primitive, and fail with a bounded timeout rather than escalating to a forced kill.
+- Extend `machine-mcp service status` to report platform-service state and workspace-daemon state separately, including whether a live legacy process was verified as service-style. This makes a launchd-unloaded but still-running daemon visible instead of presenting a misleading inactive-only status.
+
+### Tests and documentation
+
+- Add real child-process regression coverage for legacy orphan takeover, canonical `/var` versus `/private/var` path aliases, foreground-process protection, non-forcing timeout behavior, launchd service-target generation, and packaged daemon-process module presence. Update upgrade and recovery guidance for the exact npm install command and split service/daemon diagnosis.
+
 ## 0.11.0 - 2026-07-12
 
 ### Zero-configuration agent working agreements

package/README.md

@@ -79,7 +79,7 @@ On first remote start, the CLI:
 6. starts an outbound-only daemon connection;
 7. prints the Remote MCP URL and connection password.
 
-A normal `machine-mcp` invocation is a foreground start: it remains attached to the terminal and prints `info` logs. If an older autostart daemon is active after a global package upgrade, the CLI stops that service, waits up to 15 seconds for its workspace lock, and then starts the newly installed version in the foreground. A genuine foreground conflict is left untouched and reported with actionable guidance. To run only in the background, use `machine-mcp service start`; inspect its owner-only logs under `~/.local/state/machine-bridge-mcp/logs/`.
+A normal `machine-mcp` invocation is a foreground start: it remains attached to the terminal and prints `info` logs. After a global package upgrade, the CLI unloads the platform service and also checks the workspace lock for a detached/orphan `--daemon-only` process that the service manager no longer tracks. It terminates only a process whose PID, entrypoint, canonical workspace, canonical state root, and daemon-only arguments all match, waits up to 15 seconds for the PID and lock to disappear, and then starts the installed version in the foreground. A genuine foreground or unverifiable conflict is left untouched and reported with actionable guidance. To run only in the background, use `machine-mcp service start`; inspect its owner-only logs under `~/.local/state/machine-bridge-mcp/logs/`.
 
 Recommended upgrade sequence:
 
@@ -88,7 +88,7 @@ npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents ma
 machine-mcp --verbose
 ```
 
-The global install replaces files on disk but cannot hot-reload an already running Node process; the second command performs the bounded service takeover. If takeover fails, run `machine-mcp service stop`, confirm with `machine-mcp service status`, and retry.
+The global install replaces files on disk but cannot hot-reload an already running Node process; the second command performs the bounded service and orphan-daemon takeover. Use the command exactly as shown: `--omit=optional` prevents the development-only optional `fsevents` package from producing a blocked-install-script warning. If takeover fails, run `machine-mcp service status` first; it reports the platform service and workspace daemon separately. Then run `machine-mcp service stop` and retry.
 
 Use the printed values in the MCP client:
 

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Machine Bridge Browser",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Connects the current Chromium browser profile to the local Machine Bridge runtime for user-authorized automation.",
   "permissions": [
     "tabs",
@@ -29,5 +29,5 @@
   "action": {
     "default_title": "Machine Bridge Browser"
   },
-  "version_name": "0.11.0"
+  "version_name": "0.11.1"
 }

package/docs/ARCHITECTURE.md

@@ -40,6 +40,8 @@ A canonical workspace receives an independent profile, Worker name, secret set,
 
 `RelayConnection` owns remote WebSocket transport, authenticated `hello_ack` readiness, heartbeat liveness, reconnect backoff, and outage logging. Stdio mode invokes `LocalRuntime` directly without that adapter.
 
+`daemon-process.mjs` owns workspace-daemon inspection and takeover. It distinguishes platform service state from the lock-owning Node process, canonicalizes workspace/state paths before identity comparison, parses bounded process command lines without executing them, and sends `SIGTERM` only to a verified same-workspace `--daemon-only` process. CLI orchestration never treats a missing launchd/systemd job as proof that the process exited.
+
 ### Agent context and capability resolver
 
 `AgentContextManager` discovers the nearest Git/workspace scope, applies the user configuration and hierarchical `.machine-bridge/agent.json` files, selects built-in/user/root-to-target instructions, discovers bounded filesystem skills, and resolves registered commands. `default-instructions.mjs` supplies a versioned in-package working-agreement block and derives a small virtual project-context block from root filenames and bounded metadata. It reads package script names but not bodies, does not inspect dependency values or source contents, executes nothing, and writes no user/repository files. A global `model_instructions_file` is a separate user-designated session source and cannot be overridden by a project.

package/docs/OPERATIONS.md

@@ -61,7 +61,9 @@ Application UI inspection/actions require Accessibility permission for the Node/
 
 `machine-mcp` is a foreground command. It remains attached to the terminal, defaults to `info` logging, and stops on `Ctrl+C`. `machine-mcp service start` launches the installed platform service in the background and returns to the shell; that service uses `warn` logging.
 
-A global npm install changes the CLI files on disk but does not replace an already running Node process. On a normal foreground start, Machine Bridge checks whether its autostart service is active, requests a stop, waits up to 15 seconds for the old daemon lock to be released, and then continues with the newly installed version. New daemon locks record foreground/background mode and package version. If another foreground process owns the lock, Machine Bridge does not kill it or print a false readiness message; stop it with `Ctrl+C`. If a background takeover reaches its deadline, run:
+A global npm install changes the CLI files on disk but does not replace an already running Node process. On a normal foreground start, Machine Bridge unloads the platform service and then independently examines the workspace daemon lock. This second path handles a detached/orphan `--daemon-only` process that launchd/systemd/task scheduling no longer tracks, including legacy locks without mode/version metadata. Before sending `SIGTERM`, Machine Bridge verifies the live command line against the lock, entrypoint, canonical workspace, canonical state root, and daemon-only flag. It waits up to 15 seconds for both the PID and lock to disappear and never escalates to a forced kill. A foreground or unverifiable process is left untouched; stop a foreground instance with `Ctrl+C`.
+
+`machine-mcp service status [WORKSPACE]` reports two independent layers: the platform service (`active`) and `workspace_daemon`, plus `effective_active` and `orphaned_workspace_daemon` summary flags. On macOS it is possible for launchd to report inactive while a prior Node process remains alive with parent PID 1; that is an orphan-daemon condition, not proof that the daemon stopped. `service stop` now unloads the provider when present and then terminates only a verified service-style workspace daemon. If takeover reaches its deadline, run:
 
 ```sh
 machine-mcp service stop
@@ -76,6 +78,8 @@ npm install -g --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents ma
 machine-mcp --verbose
 ```
 
+Keep `--omit=optional` in the install command. Without it npm may resolve optional `fsevents` and warn that its install script was not included in `allowScripts`; Machine Bridge does not require that development-time watcher at runtime.
+
 ## Logs
 
 Remote autostart definitions prefer a stable PATH alias that resolves to the currently running Node executable and persist a sanitized absolute-only service `PATH` containing the Node/CLI directories, the installer's absolute PATH entries, and platform defaults. This avoids versioned Homebrew-style paths becoming invalid after upgrades and prevents launchd/systemd from falling back to a minimal system-only PATH. Re-run `machine-mcp service install` after changing Node installation families or PATH layout. A service-style `--daemon-only` start that finds the same workspace daemon already running is an idempotent no-op: it exits successfully without repeating warnings or readiness output; explicit policy/secret/change requests still report that changes were not applied. Autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup. On a logging-schema upgrade, bounded prior content is moved into `daemon.out.legacy.log` and `daemon.err.legacy.log`; use the active filenames when diagnosing current behavior.

package/docs/TESTING.md

@@ -18,7 +18,7 @@ The suite includes:
 - syntax validation for every shipped JavaScript entry point;
 - shared tool-catalog schema, annotation, and profile-inventory checks;
 - default working-agreement injection without user files, bounded automatic project metadata, script-body non-disclosure, user-global opt-out, repository opt-out rejection, global `model_instructions_file` injection in stdio/remote initialization, hierarchical precedence, live project/skill rescanning and fingerprints, automatic task ranking/loading, command override/removal, direct argv handling, timeout ceilings, and execution-profile denial;
-- foreground takeover of an asynchronously stopping background daemon, bounded timeout guidance, daemon lock mode/version metadata, and silent idempotent duplicate service starts;
+- foreground takeover of active and orphaned background daemons, legacy lock identification from canonicalized process arguments, foreground-process protection, actual-PID exit waiting, non-forcing timeout guidance, daemon lock mode/version metadata, launchd service-target semantics, and silent idempotent duplicate service starts;
 - machine-level browser-broker ownership/client proxying, authenticated extension origin/subprotocol, non-cacheable local pairing, pairing-token non-disclosure, resource-backed upload routing, and broker result redaction;
 - canonical path and symbolic-link escape tests;
 - relative-path privacy and error-path redaction tests;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",
@@ -44,7 +44,7 @@
     "prepublishOnly": "npm run check && npm run version:check && npm run release:check",
     "worker:types": "wrangler types src/worker/worker-configuration.d.ts",
     "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
-    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/agent-context.mjs && node --check src/local/default-instructions.mjs && node --check src/local/browser-bridge.mjs && node --check src/local/app-automation.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/release-state.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/agent-context-test.mjs && node --check tests/browser-bridge-test.mjs && node --check tests/app-automation-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/release-state-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs && node --check browser-extension/service-worker.js && node --check browser-extension/pairing.js && node --check browser-extension/page-automation.js",
+    "syntax": "sh -n mbm && node --check bin/machine-mcp.mjs && node --check src/local/cli.mjs && node --check src/local/runtime.mjs && node --check src/local/agent-context.mjs && node --check src/local/default-instructions.mjs && node --check src/local/daemon-process.mjs && node --check src/local/browser-bridge.mjs && node --check src/local/app-automation.mjs && node --check src/local/relay-connection.mjs && node --check src/local/secure-file.mjs && node --check src/local/patch.mjs && node --check src/local/process-sessions.mjs && node --check src/local/tools.mjs && node --check src/local/stdio.mjs && node --check src/local/state.mjs && node --check src/local/shell.mjs && node --check src/local/service.mjs && node --check src/local/log.mjs && node --check src/local/atomic-fs.mjs && node --check src/local/ssh-key.mjs && node --check src/local/resource-operations.mjs && node --check src/local/full-access-test.mjs && node --check src/local/managed-jobs.mjs && node --check src/local/job-runner.mjs && node --check scripts/sync-worker-version.mjs && node --check scripts/privacy-check.mjs && node --check scripts/release-impact-check.mjs && node --check scripts/network-retry.mjs && node --check scripts/release-state.mjs && node --check scripts/github-release.mjs && node --check tests/worker-integration-test.mjs && node --check tests/stdio-integration-test.mjs && node --check tests/catalog-test.mjs && node --check tests/agent-context-test.mjs && node --check tests/browser-bridge-test.mjs && node --check tests/app-automation-test.mjs && node --check tests/local-self-test.mjs && node --check tests/runtime-self-test.mjs && node --check tests/managed-jobs-test.mjs && node --check tests/ssh-key-test.mjs && node --check tests/full-access-test.mjs && node --check tests/atomic-fs-test.mjs && node --check tests/package-test.mjs && node --check tests/release-impact-test.mjs && node --check tests/release-state-test.mjs && node --check tests/privacy-test.mjs && node --check tests/network-retry-test.mjs && node --check tests/relay-connection-test.mjs && node --check tests/install-smoke-test.mjs && node --check tests/secure-file-test.mjs && node --check tests/architecture-test.mjs && node --check browser-extension/service-worker.js && node --check browser-extension/pairing.js && node --check browser-extension/page-automation.js",
     "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run typecheck && npm run syntax && npm run catalog:test && npm run agent-context:test && npm run browser-bridge:test && npm run app-automation:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",

package/src/local/cli.mjs

@@ -5,6 +5,7 @@ import path, { join, resolve } from "node:path";
 import process from "node:process";
 import readline from "node:readline/promises";
 import { LocalRuntime } from "./runtime.mjs";
+import { acquireDaemonLockWithTakeover, inspectWorkspaceDaemon, stopWorkspaceServiceDaemon } from "./daemon-process.mjs";
 import { runStdioServer } from "./stdio.mjs";
 import { assertCanonicalFullPolicy, DEFAULT_POLICY_PROFILE, DEFAULT_POLICY_REVISION, POLICY_PROFILES, normalizePolicy, policyProfile, toolsForPolicy } from "./tools.mjs";
 import { classifyOperationalError, createLogger, normalizeLogLevel, sanitizeLogText } from "./log.mjs";
@@ -47,8 +48,6 @@ const BOOLEAN_OPTIONS = new Set([
 const VALUE_OPTIONS = new Set([
   "workspace", "stateDir", "workerName", "profile", "execMode", "client", "logLevel",
 ]);
-const DAEMON_TAKEOVER_TIMEOUT_MS = 15_000;
-const DAEMON_TAKEOVER_POLL_MS = 100;
 
 const COMMAND_HANDLERS = Object.freeze({
   start: startCommand,
@@ -146,7 +145,7 @@ const ACTION_POSITIONAL_RULES = Object.freeze({
   },
   service(args) {
     const action = String(args._[0] || "status");
-    return { max: action === "install" ? 2 : 1, tooMany: `service ${action} received too many positional arguments`, workspaceConflictAfter: 1 };
+    return { max: ["install", "status", "stop", "uninstall", "remove"].includes(action) ? 2 : 1, tooMany: `service ${action} received too many positional arguments`, workspaceConflictAfter: 1 };
   },
   autostart(args) {
     return ACTION_POSITIONAL_RULES.service(args);
@@ -324,7 +323,7 @@ async function startCommand(args) {
   try {
     const startMode = await prepareStartMode(args, state, logger);
     const daemonLock = await acquireDaemonLockWithTakeover(state, {
-      waitForServiceExit: startMode.waitForServiceExit,
+      takeOverServiceOwner: startMode.takeOverServiceOwner,
       ownerMetadata: {
         mode: args.daemonOnly ? "service" : "foreground",
         version: currentPackageVersion(),
@@ -345,43 +344,15 @@ async function prepareStartMode(args, state, logger) {
   if (args.daemonOnly) {
     const { trimAutostartLogs } = await import("./service.mjs");
     trimAutostartLogs(state.paths.stateRoot);
-    return { waitForServiceExit: false };
+    return { takeOverServiceOwner: false };
   }
-  // A normal foreground start takes over from the installed background
-  // service. Service managers terminate asynchronously, so wait for the
-  // existing daemon to release its workspace lock before declaring conflict.
+  // A normal foreground start first asks the platform service manager to
+  // unload the job, then independently reclaims a verified daemon-only
+  // process. The second step handles legacy/orphan daemons that launchd or
+  // another service manager no longer tracks.
   return stopAutostartBestEffort(logger);
 }
 
-export async function acquireDaemonLockWithTakeover(state, options = {}) {
-  const ownerMetadata = options.ownerMetadata || {};
-  let lock = acquireDaemonLock(state, ownerMetadata);
-  if (lock.acquired || !options.waitForServiceExit) return lock;
-
-  const timeoutMs = Number.isFinite(Number(options.timeoutMs))
-    ? Math.max(1, Number(options.timeoutMs))
-    : DAEMON_TAKEOVER_TIMEOUT_MS;
-  const pollMs = Number.isFinite(Number(options.pollMs))
-    ? Math.max(1, Number(options.pollMs))
-    : DAEMON_TAKEOVER_POLL_MS;
-  const logger = options.logger || { info() {} };
-  const priorPid = lock.owner?.pid ? `pid ${lock.owner.pid}` : "the existing process";
-  logger.info(`waiting for the background daemon (${priorPid}) to stop before foreground startup`);
-
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    await sleep(Math.min(pollMs, Math.max(1, deadline - Date.now())));
-    lock = acquireDaemonLock(state, ownerMetadata);
-    if (lock.acquired) {
-      logger.info("background daemon stopped; foreground startup is taking over the workspace");
-      return lock;
-    }
-  }
-
-  const pid = lock.owner?.pid ? `pid ${lock.owner.pid}` : "unknown pid";
-  throw new Error(`background daemon did not release the workspace within ${Math.ceil(timeoutMs / 1000)} seconds (${pid}); run \`machine-mcp service stop\`, verify \`machine-mcp service status\`, and retry`);
-}
-
 function reportExistingDaemon(args, state, owner, logger) {
   const pid = owner?.pid ? `pid ${owner.pid}` : "unknown pid";
   if (isIdempotentDaemonOnlyStart(args)) {
@@ -1244,7 +1215,15 @@ async function serviceCommand(args) {
   const { installAutostart, uninstallAutostart, autostartStatus, startAutostart, stopAutostart } = await import("./service.mjs");
   if (action === "status") {
     const status = await autostartStatus({ logger: structuredLogger(Boolean(args.quiet)) });
-    console.log(JSON.stringify(status, null, 2));
+    const state = optionalServiceState(args, stateRoot);
+    const workspaceDaemon = state ? inspectWorkspaceDaemon(state) : null;
+    console.log(JSON.stringify({
+      ...status,
+      workspace: state?.workspace?.path || null,
+      workspace_daemon: workspaceDaemon,
+      effective_active: Boolean(status.active || workspaceDaemon?.alive),
+      orphaned_workspace_daemon: Boolean(!status.active && workspaceDaemon?.alive && workspaceDaemon?.verified_service_daemon),
+    }, null, 2));
     return;
   }
   if (action === "install") {
@@ -1264,18 +1243,48 @@ async function serviceCommand(args) {
     return;
   }
   if (action === "stop") {
-    const result = await stopAutostart({ logger: structuredLogger(Boolean(args.quiet)) });
+    const logger = structuredLogger(Boolean(args.quiet));
+    const provider = await stopAutostart({ logger });
+    const state = optionalServiceState(args, stateRoot);
+    const workspaceDaemon = state
+      ? await stopWorkspaceServiceDaemon(state, { logger, reason: "service stop" })
+      : { ok: true, found: false, stopped: false, verified_service_daemon: false, reason: "workspace_not_selected" };
+    const result = {
+      ...provider,
+      ok: provider?.ok !== false && workspaceDaemon.ok,
+      workspace: state?.workspace?.path || null,
+      workspace_daemon: workspaceDaemon,
+    };
     console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
     return;
   }
   if (action === "uninstall" || action === "remove") {
-    const result = await uninstallAutostart({ stateRoot, logger: structuredLogger(Boolean(args.quiet)) });
-    console.log(JSON.stringify(result, null, 2));
+    const logger = structuredLogger(Boolean(args.quiet));
+    const result = await uninstallAutostart({ stateRoot, logger });
+    const state = optionalServiceState(args, stateRoot);
+    const workspaceDaemon = state
+      ? await stopWorkspaceServiceDaemon(state, { logger, reason: "service uninstall" })
+      : { ok: true, found: false, stopped: false, verified_service_daemon: false, reason: "workspace_not_selected" };
+    const output = {
+      ...result,
+      ok: result?.ok !== false && workspaceDaemon.ok,
+      workspace: state?.workspace?.path || null,
+      workspace_daemon: workspaceDaemon,
+    };
+    console.log(JSON.stringify(output, null, 2));
+    if (!output.ok) process.exitCode = 1;
     return;
   }
   throw new Error(`Unknown service action: ${action}`);
 }
 
+function optionalServiceState(args, stateRoot) {
+  const requested = args.workspace || args._[1] || selectedWorkspace(stateRoot);
+  if (!requested || requested === true) return null;
+  return loadState(resolveWorkspace(String(requested)), { stateDir: stateRoot });
+}
+
 async function installAutostartBestEffort({ workspace, stateRoot, entryScript, logger }) {
   try {
     const { installAutostart } = await import("./service.mjs");
@@ -1288,24 +1297,19 @@ async function installAutostartBestEffort({ workspace, stateRoot, entryScript, l
 }
 
 async function stopAutostartBestEffort(logger) {
+  let result = null;
   try {
-    const { autostartStatus, stopAutostart } = await import("./service.mjs");
-    let status = null;
-    try {
-      status = await autostartStatus({ logger: structuredLogger(true) });
-    } catch (error) {
-      logger.debug?.("Autostart status check failed before takeover", { error_class: classifyOperationalError(error) });
-    }
-    if (status?.active === false) return { waitForServiceExit: false };
-
-    const result = await stopAutostart({ logger: structuredLogger(true) });
-    const stopSucceeded = result?.code === 0 || result?.ok === true;
-    if (status?.active && stopSucceeded) logger.info("stopping the background service before foreground startup");
-    return { waitForServiceExit: Boolean(stopSucceeded && status?.active !== false) };
+    const { stopAutostart } = await import("./service.mjs");
+    result = await stopAutostart({ logger: structuredLogger(true) });
   } catch (error) {
-    logger.warn("Autostart stop skipped", { error_class: classifyOperationalError(error) });
-    return { waitForServiceExit: false };
+    logger.warn("Autostart stop command was unavailable; checking the workspace daemon directly", { error_class: classifyOperationalError(error) });
+    return { takeOverServiceOwner: true, provider: null };
+  }
+  if (result?.active_before && result?.ok) logger.info("stopping the background service before foreground startup");
+  if (result?.ok === false && result?.active === true) {
+    throw new Error("the background service is still active after the stop request; run `machine-mcp service status` for details");
   }
+  return { takeOverServiceOwner: true, provider: result };
 }
 
 async function uninstallCommand(args) {

package/src/local/daemon-process.mjs

@@ -0,0 +1,263 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import {
+  acquireDaemonLock,
+  daemonLockPathForState,
+  readDaemonLockOwner,
+  resolveWorkspace,
+} from "./state.mjs";
+
+const DEFAULT_TAKEOVER_TIMEOUT_MS = 15_000;
+const DEFAULT_TAKEOVER_POLL_MS = 100;
+
+export async function acquireDaemonLockWithTakeover(state, options = {}) {
+  const ownerMetadata = options.ownerMetadata || {};
+  let lock = acquireDaemonLock(state, ownerMetadata);
+  if (lock.acquired || !options.takeOverServiceOwner) return lock;
+
+  const stopped = await stopWorkspaceServiceDaemon(state, {
+    owner: lock.owner,
+    timeoutMs: options.timeoutMs,
+    pollMs: options.pollMs,
+    logger: options.logger,
+    reason: "foreground startup",
+  });
+  if (!stopped.verified_service_daemon) return lock;
+  if (!stopped.ok) {
+    const pid = stopped.pid ? `pid ${stopped.pid}` : "unknown pid";
+    throw new Error(`background daemon did not release the workspace within ${Math.ceil(stopped.timeout_ms / 1000)} seconds (${pid}); run \`machine-mcp service stop\`, verify \`machine-mcp service status\`, and retry`);
+  }
+
+  lock = acquireDaemonLock(state, ownerMetadata);
+  if (lock.acquired) options.logger?.info?.("background daemon stopped; foreground startup is taking over the workspace");
+  return lock;
+}
+
+export async function stopWorkspaceServiceDaemon(state, options = {}) {
+  const timeoutMs = boundedPositiveInt(options.timeoutMs, DEFAULT_TAKEOVER_TIMEOUT_MS);
+  const pollMs = boundedPositiveInt(options.pollMs, DEFAULT_TAKEOVER_POLL_MS);
+  const logger = options.logger || { info() {}, warn() {} };
+  const deadline = Date.now() + timeoutMs;
+  const signalled = new Set();
+  let owner = options.owner || readDaemonLockOwner(daemonLockPathForState(state));
+  let verified = false;
+  let lastOwner = owner;
+
+  while (true) {
+    if (owner?.pid && isPidAlive(owner.pid)) {
+      lastOwner = owner;
+      const identity = inspectWorkspaceDaemonOwner(state, owner);
+      if (!identity.verified_service_daemon) {
+        return {
+          ok: false,
+          found: true,
+          verified_service_daemon: false,
+          reason: identity.reason,
+          timeout_ms: timeoutMs,
+          ...publicDaemonOwner(owner),
+        };
+      }
+      verified = true;
+      if (!signalled.has(Number(owner.pid))) {
+        const purpose = options.reason || "service stop";
+        logger.info?.(`stopping detached background daemon (pid ${owner.pid}) for ${purpose}`);
+        try {
+          process.kill(Number(owner.pid), "SIGTERM");
+        } catch (error) {
+          if (error?.code !== "ESRCH") {
+            return {
+              ok: false,
+              found: true,
+              verified_service_daemon: true,
+              reason: "signal_failed",
+              timeout_ms: timeoutMs,
+              ...publicDaemonOwner(owner),
+            };
+          }
+        }
+        signalled.add(Number(owner.pid));
+      }
+    }
+
+    const liveSignalled = [...signalled].filter((pid) => isPidAlive(pid));
+    const currentOwnerAlive = Boolean(owner?.pid && isPidAlive(owner.pid));
+    if (!currentOwnerAlive && liveSignalled.length === 0) break;
+
+    if (Date.now() >= deadline) {
+      logger.warn?.(`detached background daemon did not stop within ${Math.ceil(timeoutMs / 1000)} seconds`);
+      const remainingPid = Number(owner?.pid) || liveSignalled[0] || null;
+      return {
+        ok: false,
+        found: true,
+        stopped: false,
+        verified_service_daemon: verified,
+        reason: "timeout",
+        timeout_ms: timeoutMs,
+        pid: remainingPid,
+        mode: publicDaemonMode(lastOwner),
+        version: typeof lastOwner?.version === "string" ? lastOwner.version : "unknown",
+      };
+    }
+    await sleep(Math.min(pollMs, Math.max(1, deadline - Date.now())));
+    owner = readDaemonLockOwner(daemonLockPathForState(state));
+  }
+
+  // Reclaim a stale lock only through the normal token-aware primitive.
+  const staleCleanup = acquireDaemonLock(state, { mode: "service" });
+  if (staleCleanup.acquired) staleCleanup.release();
+  return {
+    ok: true,
+    found: verified,
+    stopped: verified,
+    verified_service_daemon: verified,
+    reason: verified ? "stopped" : "not_running",
+    timeout_ms: timeoutMs,
+    ...(lastOwner ? publicDaemonOwner(lastOwner) : {}),
+  };
+}
+
+export function inspectWorkspaceDaemon(state) {
+  const owner = readDaemonLockOwner(daemonLockPathForState(state));
+  if (!owner) return { present: false, alive: false, verified_service_daemon: false };
+  const alive = Boolean(owner.pid && isPidAlive(owner.pid));
+  const identity = alive
+    ? inspectWorkspaceDaemonOwner(state, owner)
+    : { verified_service_daemon: false, reason: "stale_lock" };
+  return {
+    present: true,
+    alive,
+    verified_service_daemon: identity.verified_service_daemon,
+    identity_reason: identity.reason,
+    ...publicDaemonOwner(owner),
+  };
+}
+
+function inspectWorkspaceDaemonOwner(state, owner) {
+  if (!owner || owner.purpose !== "daemon") return { verified_service_daemon: false, reason: "invalid_lock_owner" };
+  const pid = Number(owner.pid);
+  if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return { verified_service_daemon: false, reason: "invalid_pid" };
+  if (!sameCanonicalPath(owner.workspace, state.workspace.path)) return { verified_service_daemon: false, reason: "workspace_mismatch" };
+  if (owner.mode === "foreground") return { verified_service_daemon: false, reason: "foreground_daemon" };
+
+  const command = processCommandLine(pid);
+  if (!command) {
+    return { verified_service_daemon: false, reason: owner.mode === "service" ? "service_identity_unavailable" : "legacy_identity_unavailable" };
+  }
+  const argv = splitProcessCommandLine(command);
+  const entryName = path.basename(String(owner.entryScript || "machine-mcp"));
+  const workspaceArg = commandFlagValue(argv, "--workspace");
+  const stateRootArg = commandFlagValue(argv, "--state-dir");
+  const entryMatches = argv.some((value) => {
+    const name = path.basename(value);
+    return name === entryName || name === "machine-mcp" || name === "machine-mcp.mjs";
+  });
+  const matches = argv.includes("--daemon-only")
+    && sameCanonicalPath(workspaceArg, state.workspace.path)
+    && sameCanonicalPath(stateRootArg, state.paths.stateRoot)
+    && entryMatches;
+  return { verified_service_daemon: matches, reason: matches ? "service_command" : "command_mismatch" };
+}
+
+function processCommandLine(pid) {
+  if (process.platform === "win32") {
+    const command = `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine`;
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], {
+      encoding: "utf8",
+      timeout: 3000,
+      windowsHide: true,
+    });
+    return result.status === 0 ? String(result.stdout || "").trim() : "";
+  }
+  const result = spawnSync("ps", ["-ww", "-p", String(pid), "-o", "command="], {
+    encoding: "utf8",
+    timeout: 3000,
+    windowsHide: true,
+  });
+  return result.status === 0 ? String(result.stdout || "").trim() : "";
+}
+
+function splitProcessCommandLine(value) {
+  const args = [];
+  let current = "";
+  let quote = "";
+  const text = String(value);
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (quote) {
+      if (character === quote) quote = "";
+      else if (character === "\\" && quote === '"' && ['"', "\\"].includes(text[index + 1])) {
+        current += text[index + 1];
+        index += 1;
+      } else current += character;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      if (current) {
+        args.push(current);
+        current = "";
+      }
+      continue;
+    }
+    if (character === "\\" && /[\s'"\\]/.test(text[index + 1] || "")) {
+      current += text[index + 1];
+      index += 1;
+      continue;
+    }
+    current += character;
+  }
+  if (current) args.push(current);
+  return args;
+}
+
+function commandFlagValue(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 && index + 1 < argv.length ? argv[index + 1] : "";
+}
+
+function sameCanonicalPath(left, right) {
+  if (typeof left !== "string" || typeof right !== "string") return false;
+  try {
+    const a = resolveWorkspace(left);
+    const b = resolveWorkspace(right);
+    return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+  } catch {
+    return false;
+  }
+}
+
+function publicDaemonOwner(owner) {
+  return {
+    pid: Number(owner?.pid) || null,
+    mode: publicDaemonMode(owner),
+    version: typeof owner?.version === "string" ? owner.version : "unknown",
+  };
+}
+
+function publicDaemonMode(owner) {
+  return owner?.mode === "service" || owner?.mode === "foreground" ? owner.mode : "legacy";
+}
+
+function isPidAlive(pid) {
+  const parsed = Number(pid);
+  if (!Number.isInteger(parsed) || parsed <= 0) return false;
+  try {
+    process.kill(parsed, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function boundedPositiveInt(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.max(1, parsed) : fallback;
+}
+
+function sleep(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}

package/src/local/service.mjs

@@ -248,6 +248,18 @@ function launchdPlistPath() {
   return path.join(os.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
 }
 
+export function launchdServiceTarget(uid = process.getuid?.()) {
+  const parsed = Number(uid);
+  if (!Number.isInteger(parsed) || parsed < 0) throw new Error("launchd requires a numeric user id");
+  return `gui/${parsed}/${LABEL}`;
+}
+
+function launchdDomainTarget(uid = process.getuid?.()) {
+  const parsed = Number(uid);
+  if (!Number.isInteger(parsed) || parsed < 0) throw new Error("launchd requires a numeric user id");
+  return `gui/${parsed}`;
+}
+
 async function installLaunchd(spec, logger) {
   const plistPath = launchdPlistPath();
   mkdirSync(path.dirname(plistPath), { recursive: true });
@@ -259,34 +271,73 @@ async function installLaunchd(spec, logger) {
 
 async function startLaunchd(logger) {
   const plistPath = launchdPlistPath();
-  const target = `gui/${process.getuid?.() ?? ""}`;
+  const target = launchdDomainTarget();
   if (!existsSync(plistPath)) return { ok: false, error: "launchd plist not installed" };
-  await serviceRun("launchctl", ["bootout", target, plistPath]);
+  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}`]);
-  logger.info?.("launchd service started");
-  return { ok: boot.code === 0 || kick.code === 0, bootstrap: boot, kickstart: kick };
+  const ok = boot.code === 0 || kick.code === 0;
+  if (ok) logger.info?.("launchd service started");
+  else logger.warn?.("launchd service failed to start");
+  return { ok, provider: "launchd", bootstrap: boot, kickstart: kick };
 }
 
 async function stopLaunchd(logger) {
   const plistPath = launchdPlistPath();
-  const target = `gui/${process.getuid?.() ?? ""}`;
-  const result = await serviceRun("launchctl", ["bootout", target, plistPath]);
-  logger.info?.("launchd service stopped");
-  return result;
+  const domainTarget = launchdDomainTarget();
+  const serviceTarget = launchdServiceTarget();
+  const before = await statusLaunchd();
+  if (!before.active) {
+    logger.info?.("launchd service is not loaded");
+    return {
+      ok: true,
+      provider: "launchd",
+      installed: existsSync(plistPath),
+      active_before: false,
+      active: false,
+      already_stopped: true,
+      code: 0,
+      stdout: "",
+      stderr: "",
+    };
+  }
+
+  const byServiceTarget = await serviceRun("launchctl", ["bootout", serviceTarget]);
+  const byPlist = byServiceTarget.code === 0
+    ? null
+    : await serviceRun("launchctl", ["bootout", domainTarget, plistPath]);
+  const after = await statusLaunchd();
+  const rawResult = byPlist || byServiceTarget;
+  const ok = !after.active;
+  if (ok) logger.info?.("launchd service stopped");
+  else logger.warn?.("launchd service is still active after the stop request");
+  return {
+    ...rawResult,
+    ok,
+    provider: "launchd",
+    installed: existsSync(plistPath),
+    active_before: true,
+    active: after.active,
+    already_stopped: false,
+    code: ok ? 0 : rawResult.code,
+    bootout_service_target: byServiceTarget,
+    ...(byPlist ? { bootout_plist_fallback: byPlist } : {}),
+  };
 }
 
 async function uninstallLaunchd(logger) {
-  await stopLaunchd(logger).catch(() => {});
+  const stopped = await stopLaunchd(logger);
   const plistPath = launchdPlistPath();
+  if (!stopped.ok) return { ok: false, provider: "launchd", path: plistPath, stop: stopped };
   if (existsSync(plistPath)) rmSync(plistPath, { force: true });
   logger.info?.("Autostart removed.");
-  return { ok: true, provider: "launchd", path: plistPath };
+  return { ok: true, provider: "launchd", path: plistPath, stop: stopped };
 }
 
 async function statusLaunchd() {
   const plistPath = launchdPlistPath();
-  const target = `gui/${process.getuid?.() ?? ""}/${LABEL}`;
+  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 };
 }

package/src/worker/index.ts

@@ -3,7 +3,7 @@ import toolCatalog from "../shared/tool-catalog.json";
 import serverMetadata from "../shared/server-metadata.json";
 
 const SERVER_NAME = String(serverMetadata.name);
-const SERVER_VERSION = "0.11.0";
+const SERVER_VERSION = "0.11.1";
 const MCP_PROTOCOL_VERSION = String(serverMetadata.protocolVersion);
 const MCP_SUPPORTED_PROTOCOL_VERSIONS = serverMetadata.supportedProtocolVersions.map((value) => String(value));
 const JSONRPC_VERSION = "2.0";