machine-bridge-mcp 0.4.2 → 0.5.0

package/src/local/daemon.mjs

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
-import { chmod, link, lstat, mkdir, opendir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, link, lstat, mkdir, open, opendir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path, { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import WebSocket from "ws";
@@ -9,7 +9,8 @@ import { applyUpdateHunks, parsePatchEnvelope } from "./patch.mjs";
 import { executionEnv, workspaceShellCommand } from "./shell.mjs";
 import { MAX_COMMAND_BYTES, ProcessSessionManager, terminateProcessTree, validateArgv } from "./process-sessions.mjs";
 export { MAX_COMMAND_BYTES } from "./process-sessions.mjs";
-import { MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, normalizePolicy, toolNamesForPolicy } from "./tools.mjs";
+import { MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, normalizePolicy, SERVER_NAME, toolNamesForPolicy } from "./tools.mjs";
+import { classifyOperationalError } from "./log.mjs";
 
 export const MAX_WRITE_BYTES = 5 * 1024 * 1024;
 const MAX_WS_MESSAGE_BYTES = 8 * 1024 * 1024;
@@ -18,6 +19,7 @@ const MAX_DIRECTORY_ENTRIES = 10_000;
 const MAX_PATH_RESULT_BYTES = 4 * 1024 * 1024;
 const MAX_WALK_ENTRIES = 200_000;
 const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+const SLOW_TOOL_CALL_MS = 30_000;
 
 export class LocalDaemon {
   constructor({ workerUrl = "", secret = "", workspace, policy, logger = console, onSuperseded = null }) {
@@ -66,12 +68,18 @@ export class LocalDaemon {
 
   runtimeInfo() {
     return {
-      name: "machine-bridge-mcp",
+      name: SERVER_NAME,
       protocol_version: MCP_PROTOCOL_VERSION,
       supported_protocol_versions: MCP_SUPPORTED_PROTOCOL_VERSIONS,
       workspace: this.displayPath(this.workspace),
       workspace_name: basename(this.workspace),
       policy: this.policy,
+      enforcement: {
+        filesystem_scope: this.policy.unrestrictedPaths ? "local-user-accessible" : "workspace",
+        sensitive_filename_filter: false,
+        operating_system_permissions_apply: true,
+        host_policy_is_independent: true,
+      },
       tools: ["server_info", ...this.tools()],
       runtime: {
         environment: this.policy.minimalEnv ? "isolated-minimal" : "full-parent",
@@ -109,7 +117,7 @@ export class LocalDaemon {
   connect() {
     if (this.closed) return;
     const wsUrl = `${this.workerUrl.replace(/^http/i, "ws")}/daemon/ws`;
-    this.logger.info?.("connecting daemon websocket", { endpoint: redactUrl(wsUrl) });
+    this.logger.debug?.("connecting to remote relay", { endpoint: redactUrl(wsUrl) });
     const socket = new WebSocket(wsUrl, { headers: { "X-Bridge-Token": this.secret } });
     this.ws = socket;
 
@@ -119,7 +127,7 @@ export class LocalDaemon {
         return;
       }
       this.reconnectAttempt = 0;
-      this.logger.info?.("daemon websocket connected");
+      this.logger.info?.("remote relay connected");
       this.send({ type: "hello", tools: this.tools(), policy: this.policy, protocol_versions: MCP_SUPPORTED_PROTOCOL_VERSIONS });
       if (this.connectedOnceResolve) {
         this.connectedOnceResolve(true);
@@ -138,7 +146,7 @@ export class LocalDaemon {
         return;
       }
       void this.handleMessage(raw).catch(error => {
-        this.logger.error?.("daemon message handler failed", { error: this.safeErrorMessage(error) });
+        this.logger.error?.("daemon message handler failed", { error_class: classifyOperationalError(error) });
       });
     });
 
@@ -157,13 +165,13 @@ export class LocalDaemon {
         this.logger.warn?.("daemon connection permanently superseded", fields);
         queueMicrotask(() => {
           try { this.onSuperseded?.(); } catch (error) {
-            this.logger.error?.("daemon superseded callback failed", { error_class: classifyError(error) });
+            this.logger.error?.("daemon superseded callback failed", { error_class: classifyOperationalError(error) });
           }
         });
         return;
       }
-      if (this.closed) this.logger.info?.("daemon websocket closed", fields);
-      else this.logger.warn?.("daemon websocket disconnected", fields);
+      if (this.closed) this.logger.debug?.("remote relay closed", fields);
+      else this.logger.warn?.("remote relay disconnected", fields);
       if (!this.closed) {
         const delay = reconnectDelay(this.reconnectAttempt++);
         this.logger.debug?.("scheduling daemon reconnect", { delay_ms: delay });
@@ -174,8 +182,8 @@ export class LocalDaemon {
 
     socket.on("error", error => {
       if (this.ws !== socket) return;
-      if (this.closed) this.logger.info?.("daemon websocket closed during shutdown", { error: boundedErrorMessage(error) });
-      else this.logger.error?.("daemon websocket error", { error: boundedErrorMessage(error) });
+      if (this.closed) this.logger.debug?.("remote relay closed during shutdown", { error_class: classifyOperationalError(error) });
+      else this.logger.error?.("remote relay error", { error_class: classifyOperationalError(error) });
     });
   }
 
@@ -185,7 +193,7 @@ export class LocalDaemon {
       this.ws.send(JSON.stringify(value));
       return true;
     } catch (error) {
-      this.logger.warn?.("daemon websocket send failed", { error: boundedErrorMessage(error) });
+      this.logger.warn?.("remote relay send failed", { error_class: classifyOperationalError(error) });
       return false;
     }
   }
@@ -229,11 +237,15 @@ export class LocalDaemon {
       const result = await this.executeTool(tool, argumentsValue, { callId: id });
       if (this.cancelledCalls.has(id)) throw new Error("tool call cancelled");
       this.send({ type: "tool_result", id, ok: true, result });
-      this.logger.info?.("tool call completed", { call_id: shortCallId(id), tool, duration_ms: Date.now() - started, ok: true });
+      const durationMs = Date.now() - started;
+      if (durationMs >= SLOW_TOOL_CALL_MS) this.logger.info?.("slow tool call completed", { tool, duration_ms: durationMs });
+      else this.logger.debug?.("tool call completed", { call_id: shortCallId(id), tool, duration_ms: durationMs });
     } catch (error) {
       const safeError = this.safeErrorMessage(error);
       this.send({ type: "tool_result", id, ok: false, error: { message: safeError } });
-      this.logger.warn?.("tool call failed", { call_id: shortCallId(id), tool, duration_ms: Date.now() - started, ok: false, error_class: classifyError(error) });
+      const durationMs = Date.now() - started;
+      this.logger.warn?.("tool call failed", { tool, duration_ms: durationMs, error_class: classifyOperationalError(error) });
+      this.logger.debug?.("tool call failure correlation", { call_id: shortCallId(id) });
     } finally {
       clearTimeout(deadline);
       this.activeToolCalls -= 1;
@@ -258,7 +270,7 @@ export class LocalDaemon {
       }, 2000);
       timer.unref?.();
     }
-    this.logger.info?.("tool call cancellation requested", { call_id: shortCallId(callId), reason });
+    this.logger.debug?.("tool call cancellation requested", { call_id: shortCallId(callId), reason });
   }
 
   async executeTool(tool, args, context = {}) {
@@ -366,11 +378,9 @@ export class LocalDaemon {
     }
     if (!args.path) throw new Error("path is required");
     const full = await this.resolveExistingPath(args.path);
-    const info = await stat(full);
-    if (!info.isFile()) throw new Error("path is not a file");
-    if (info.size > MAX_WRITE_BYTES) throw new Error(`file exceeds maximum readable text size (${info.size} > ${MAX_WRITE_BYTES})`);
     this.throwIfCancelled(context);
-    const content = await readUtf8File(full);
+    const { buffer, info } = await readBoundedFile(full, MAX_WRITE_BYTES, "readable text file");
+    const content = decodeUtf8(buffer);
     this.throwIfCancelled(context);
     const maxBytes = clampInt(args.max_bytes, 1024 * 1024, 1, MAX_WRITE_BYTES);
     const startLine = args.start_line === undefined ? 1 : clampInt(args.start_line, 1, 1, Number.MAX_SAFE_INTEGER);
@@ -399,11 +409,8 @@ export class LocalDaemon {
   async viewImage(args, context = {}) {
     if (!args.path) throw new Error("path is required");
     const full = await this.resolveExistingPath(args.path);
-    const info = await stat(full);
-    if (!info.isFile()) throw new Error("path is not a file");
-    if (info.size > MAX_IMAGE_BYTES) throw new Error(`image exceeds maximum size (${info.size} > ${MAX_IMAGE_BYTES})`);
     this.throwIfCancelled(context);
-    const buffer = await readFile(full);
+    const { buffer, info } = await readBoundedFile(full, MAX_IMAGE_BYTES, "image");
     this.throwIfCancelled(context);
     const mimeType = detectImageMime(buffer);
     if (!mimeType) throw new Error("unsupported image format; expected PNG, JPEG, GIF, or WebP");
@@ -545,10 +552,9 @@ export class LocalDaemon {
 
   async searchOneFile(full, query, matches, max, context = {}) {
     this.throwIfCancelled(context);
-    const info = await stat(full).catch(() => null);
-    if (!info?.isFile() || info.size > 1024 * 1024) return;
-    const buffer = await readFile(full).catch(() => null);
-    if (!buffer || buffer.includes(0)) return;
+    const bounded = await readBoundedFile(full, 1024 * 1024, "search file").catch(() => null);
+    if (!bounded || bounded.buffer.includes(0)) return;
+    const buffer = bounded.buffer;
     let text;
     try { text = new TextDecoder("utf-8", { fatal: true }).decode(buffer); } catch { return; }
     if (!text) return;
@@ -850,13 +856,36 @@ function assertContainedPath(root, target) {
   throw new Error("path is outside the configured workspace; restart with --unrestricted-paths to allow it");
 }
 
-async function readUtf8File(filePath) {
-  const buffer = await readFile(filePath);
+async function readBoundedFile(filePath, maxBytes, label) {
+  const handle = await open(filePath, "r");
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) throw new Error(`${label} is not a regular file`);
+    if (info.size > maxBytes) throw new Error(`${label} exceeds maximum size (${info.size} > ${maxBytes})`);
+    const buffer = Buffer.alloc(info.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    return { buffer: buffer.subarray(0, offset), info };
+  } finally {
+    await handle.close();
+  }
+}
+
+function decodeUtf8(buffer) {
   try { return new TextDecoder("utf-8", { fatal: true }).decode(buffer); } catch {
     throw new Error("file is not valid UTF-8 text");
   }
 }
 
+async function readUtf8File(filePath) {
+  const { buffer } = await readBoundedFile(filePath, MAX_WRITE_BYTES, "text file");
+  return decodeUtf8(buffer);
+}
+
 async function atomicWriteText(full, content, existing = null, options = {}) {
   await mkdir(dirname(full), { recursive: true });
   const temp = join(dirname(full), `.${basename(full)}.mbm-${process.pid}-${randomBytes(6).toString("hex")}.tmp`);
@@ -1010,18 +1039,6 @@ function isPlainRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
-function classifyError(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  if (/cancel/i.test(message)) return "cancelled";
-  if (/timed out/i.test(message)) return "timeout";
-  if (/outside the configured workspace/i.test(message)) return "path_boundary";
-  if (/disabled by daemon policy|requires .* mode/i.test(message)) return "policy_denied";
-  if (/not found|ENOENT/i.test(message)) return "not_found";
-  if (/permission|EACCES|EPERM/i.test(message)) return "permission_denied";
-  if (/maximum|exceeds|max_bytes|too many/i.test(message)) return "limit_exceeded";
-  if (/invalid|must|requires|ambiguous|mismatch/i.test(message)) return "invalid_request";
-  return "execution_failed";
-}
 
 function equivalentPathPrefixes(...values) {
   const prefixes = new Set(values.filter(Boolean).map((value) => String(value)));

package/src/local/log.mjs

@@ -9,6 +9,11 @@ const COLORS = {
   gray: "\x1b[90m",
 };
 
+const MAX_LOG_MESSAGE_CHARS = 2048;
+const MAX_LOG_FIELD_CHARS = 4096;
+const MAX_LOG_ARRAY_ITEMS = 32;
+const MAX_LOG_OBJECT_KEYS = 48;
+const LEVEL_RANK = Object.freeze({ debug: 10, info: 20, success: 20, warn: 30, error: 40 });
 const SENSITIVE_KEY = /(authorization|cookie|password|passwd|secret|token|api[_-]?key|private[_-]?key|credential)/i;
 const SECRET_VALUE = /\b(?:mcp_password|daemon_secret|token_version|mcp_at|mcp_code)_[A-Za-z0-9_-]+\b/g;
 const BEARER_VALUE = /\bBearer\s+[A-Za-z0-9._~+\/-]+=*\b/gi;
@@ -16,23 +21,26 @@ const BEARER_VALUE = /\bBearer\s+[A-Za-z0-9._~+\/-]+=*\b/gi;
 export function createLogger(options = {}) {
   const quiet = Boolean(options.quiet);
   const verbose = Boolean(options.verbose);
-  const component = sanitizeLogText(options.component ? String(options.component) : "cli");
+  const minimumLevel = normalizeLogLevel(options.level || (quiet ? "error" : verbose ? "debug" : "info"));
+  const component = sanitizeLogText(options.component ? String(options.component) : "cli", 128);
   const useColor = shouldUseColor(options);
+  const stdout = options.stderrOnly ? process.stderr : process.stdout;
 
   const write = (stream, level, label, color, message, fields) => {
-    if (quiet && level !== "error") return;
-    if (level === "debug" && !verbose) return;
+    if (LEVEL_RANK[level] < LEVEL_RANK[minimumLevel]) return;
     const prefix = useColor ? `${color}${label}${COLORS.reset}` : label;
     const suffix = formatFields(fields);
-    stream.write(`${prefix} ${component}: ${sanitizeLogText(message)}${suffix}\n`);
+    stream.write(`${prefix} ${component}: ${sanitizeLogText(message, MAX_LOG_MESSAGE_CHARS)}${suffix}\n`);
   };
 
   return {
+    verbose: minimumLevel === "debug",
+    level: minimumLevel,
     child(childComponent) {
       return createLogger({ ...options, component: childComponent });
     },
-    info(message, fields) { write(process.stdout, "info", "[info]", COLORS.blue, message, fields); },
-    success(message, fields) { write(process.stdout, "success", "[ok]", COLORS.green, message, fields); },
+    info(message, fields) { write(stdout, "info", "[info]", COLORS.blue, message, fields); },
+    success(message, fields) { write(stdout, "success", "[ok]", COLORS.green, message, fields); },
     warn(message, fields) { write(process.stderr, "warn", "[warn]", COLORS.yellow, message, fields); },
     error(message, fields) { write(process.stderr, "error", "[error]", COLORS.red, message, fields); },
     debug(message, fields) { write(process.stderr, "debug", "[debug]", COLORS.gray, message, fields); },
@@ -41,13 +49,41 @@ export function createLogger(options = {}) {
   };
 }
 
-export function redactSecret(value) {
-  return value ? "<redacted>" : "<empty>";
+export function normalizeLogLevel(value = "info") {
+  const level = String(value || "info").trim().toLowerCase();
+  if (!Object.prototype.hasOwnProperty.call(LEVEL_RANK, level) || level === "success") {
+    throw new Error("log level must be one of: error, warn, info, debug");
+  }
+  return level;
+}
+
+
+export function classifyOperationalError(error) {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  if (/cancel/i.test(message)) return "cancelled";
+  if (/timed out/i.test(message)) return "timeout";
+  if (/outside the configured workspace/i.test(message)) return "path_boundary";
+  if (/disabled|requires .* mode/i.test(message)) return "policy_denied";
+  if (/not found|ENOENT/i.test(message)) return "not_found";
+  if (/permission|EACCES|EPERM/i.test(message)) return "permission_denied";
+  if (/maximum|exceeds|max_bytes|too many/i.test(message)) return "limit_exceeded";
+  if (/invalid|must|requires|ambiguous|mismatch/i.test(message)) return "invalid_request";
+  return "execution_failed";
 }
 
 export function formatFields(fields) {
-  if (!fields || typeof fields !== "object" || !Object.keys(fields).length) return "";
-  return ` ${JSON.stringify(sanitizeLogValue(fields))}`;
+  try {
+    if (!fields || typeof fields !== "object" || !Object.keys(fields).length) return "";
+    const sanitized = sanitizeLogValue(fields);
+    const json = JSON.stringify(sanitized);
+    if (json.length <= MAX_LOG_FIELD_CHARS) return ` ${json}`;
+    return ` ${JSON.stringify({
+      fields_truncated: true,
+      field_names: Object.keys(fields).slice(0, MAX_LOG_OBJECT_KEYS),
+    })}`;
+  } catch {
+    return ' {"fields_unavailable":true}';
+  }
 }
 
 export function sanitizeLogValue(value, key = "", seen = new WeakSet(), depth = 0) {
@@ -56,23 +92,28 @@ export function sanitizeLogValue(value, key = "", seen = new WeakSet(), depth =
   if (typeof value === "string") return sanitizeLogText(value);
   if (typeof value === "bigint") return value.toString();
   if (value === null || typeof value !== "object") return value;
-  if (depth >= 8) return "<max-depth>";
+  if (depth >= 6) return "<max-depth>";
   if (seen.has(value)) return "<circular>";
   seen.add(value);
-  if (Array.isArray(value)) return value.slice(0, 100).map(item => sanitizeLogValue(item, "", seen, depth + 1));
+  if (Array.isArray(value)) return value.slice(0, MAX_LOG_ARRAY_ITEMS).map(item => sanitizeLogValue(item, "", seen, depth + 1));
   const out = {};
-  for (const [childKey, childValue] of Object.entries(value).slice(0, 100)) {
+  for (const [childKey, childValue] of Object.entries(value).slice(0, MAX_LOG_OBJECT_KEYS)) {
     out[childKey] = sanitizeLogValue(childValue, childKey, seen, depth + 1);
   }
   return out;
 }
 
-export function sanitizeLogText(value) {
-  return String(value ?? "")
+export function sanitizeLogText(value, maxChars = MAX_LOG_MESSAGE_CHARS) {
+  let raw;
+  try { raw = String(value ?? ""); } catch { raw = "<unprintable>"; }
+  const sanitized = raw
     .replace(SECRET_VALUE, "<redacted-secret>")
     .replace(BEARER_VALUE, "Bearer <redacted>")
     .replace(/[\r\n\t]/g, match => match === "\t" ? "\\t" : "\\n")
     .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "?");
+  if (!Number.isFinite(Number(maxChars)) || Number(maxChars) <= 0) return "";
+  const limit = Math.max(16, Number(maxChars));
+  return sanitized.length > limit ? `${sanitized.slice(0, limit - 1)}…` : sanitized;
 }
 
 function shouldUseColor(options) {

package/src/local/service.mjs

@@ -6,6 +6,15 @@ import { ensureOwnerOnlyDir, expandHome } from "./state.mjs";
 
 const LABEL = "dev.machine-bridge-mcp.daemon";
 const WINDOWS_TASK = "MachineBridgeMCP";
+const SERVICE_COMMAND_OUTPUT_BYTES = 64 * 1024;
+
+function serviceRun(command, args) {
+  return run(command, args, {
+    capture: true,
+    allowFailure: true,
+    maxOutputBytes: SERVICE_COMMAND_OUTPUT_BYTES,
+  });
+}
 
 export async function installAutostart({ workspace, stateRoot, entryScript, logger = console }) {
   const spec = serviceSpec({ workspace, stateRoot, entryScript });
@@ -28,14 +37,14 @@ export async function autostartStatus({ logger = console } = {}) {
 
 export async function startAutostart({ logger = console } = {}) {
   if (process.platform === "darwin") return startLaunchd(logger);
-  if (process.platform === "win32") return run("schtasks", ["/Run", "/TN", WINDOWS_TASK], { capture: true, allowFailure: true });
-  return run("systemctl", ["--user", "start", "machine-bridge-mcp.service"], { capture: true, allowFailure: true });
+  if (process.platform === "win32") return serviceRun("schtasks", ["/Run", "/TN", WINDOWS_TASK]);
+  return serviceRun("systemctl", ["--user", "start", "machine-bridge-mcp.service"]);
 }
 
 export async function stopAutostart({ logger = console } = {}) {
   if (process.platform === "darwin") return stopLaunchd(logger);
-  if (process.platform === "win32") return run("schtasks", ["/End", "/TN", WINDOWS_TASK], { capture: true, allowFailure: true });
-  return run("systemctl", ["--user", "stop", "machine-bridge-mcp.service"], { capture: true, allowFailure: true });
+  if (process.platform === "win32") return serviceRun("schtasks", ["/End", "/TN", WINDOWS_TASK]);
+  return serviceRun("systemctl", ["--user", "stop", "machine-bridge-mcp.service"]);
 }
 
 
@@ -50,21 +59,31 @@ export function trimAutostartLogs(stateRoot, options = {}) {
       const info = statSync(file);
       if (info.size > maxBytes) {
         const fd = openSync(file, "r");
+        let buffer;
         try {
           const current = fstatSync(fd);
           const length = Math.min(keepBytes, current.size);
-          const buffer = Buffer.alloc(length);
+          buffer = Buffer.alloc(length);
           readSync(fd, buffer, 0, length, Math.max(0, current.size - length));
-          writeFileSync(file, buffer, { mode: 0o600 });
         } finally {
           closeSync(fd);
         }
+        writeFileSync(file, lineSafeTail(buffer), { mode: 0o600 });
       }
       chmodSync(file, 0o600);
     } catch {}
   }
 }
 
+function lineSafeTail(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length === 0) return Buffer.alloc(0);
+  let text = buffer.toString("utf8");
+  const firstNewline = text.indexOf("\n");
+  if (firstNewline >= 0 && firstNewline < text.length - 1) text = text.slice(firstNewline + 1);
+  else text = text.replace(/^\uFFFD+/, "");
+  return Buffer.from(text, "utf8");
+}
+
 function serviceSpec({ workspace, stateRoot, entryScript }) {
   const root = expandHome(stateRoot);
   const logs = path.join(root, "logs");
@@ -92,7 +111,7 @@ export function daemonArgs(spec) {
     "--workspace", spec.workspace,
     "--state-dir", spec.stateRoot,
     "--no-print-credentials",
-    "--quiet",
+    "--log-level", "warn",
   ];
 }
 
@@ -113,9 +132,9 @@ async function startLaunchd(logger) {
   const plistPath = launchdPlistPath();
   const target = `gui/${process.getuid?.() ?? ""}`;
   if (!existsSync(plistPath)) return { ok: false, error: "launchd plist not installed" };
-  await run("launchctl", ["bootout", target, plistPath], { capture: true, allowFailure: true });
-  const boot = await run("launchctl", ["bootstrap", target, plistPath], { capture: true, allowFailure: true });
-  const kick = await run("launchctl", ["kickstart", "-k", `${target}/${LABEL}`], { capture: true, allowFailure: true });
+  await serviceRun("launchctl", ["bootout", target, plistPath]);
+  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 };
 }
@@ -123,7 +142,7 @@ async function startLaunchd(logger) {
 async function stopLaunchd(logger) {
   const plistPath = launchdPlistPath();
   const target = `gui/${process.getuid?.() ?? ""}`;
-  const result = await run("launchctl", ["bootout", target, plistPath], { capture: true, allowFailure: true });
+  const result = await serviceRun("launchctl", ["bootout", target, plistPath]);
   logger.info?.("launchd service stopped");
   return result;
 }
@@ -139,7 +158,7 @@ async function uninstallLaunchd(logger) {
 async function statusLaunchd() {
   const plistPath = launchdPlistPath();
   const target = `gui/${process.getuid?.() ?? ""}/${LABEL}`;
-  const result = await run("launchctl", ["print", target], { capture: true, allowFailure: true });
+  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 };
 }
 
@@ -173,25 +192,25 @@ async function installSystemd(spec, logger) {
   const servicePath = systemdPath();
   mkdirSync(path.dirname(servicePath), { recursive: true });
   writeFileSync(servicePath, systemdUnit(spec), { mode: 0o644 });
-  const reload = await run("systemctl", ["--user", "daemon-reload"], { capture: true, allowFailure: true });
-  const enable = await run("systemctl", ["--user", "enable", "machine-bridge-mcp.service"], { capture: true, allowFailure: true });
-  const linger = await run("loginctl", ["enable-linger", os.userInfo().username], { capture: true, allowFailure: true });
+  const reload = await serviceRun("systemctl", ["--user", "daemon-reload"]);
+  const enable = await serviceRun("systemctl", ["--user", "enable", "machine-bridge-mcp.service"]);
+  const linger = await serviceRun("loginctl", ["enable-linger", os.userInfo().username]);
   logger.info?.(`Autostart installed: ${servicePath}`);
   return { ok: reload.code === 0 && enable.code === 0, provider: "systemd", path: servicePath, reload, enable, linger };
 }
 
 async function uninstallSystemd(logger) {
-  await run("systemctl", ["--user", "disable", "--now", "machine-bridge-mcp.service"], { capture: true, allowFailure: true });
+  await serviceRun("systemctl", ["--user", "disable", "--now", "machine-bridge-mcp.service"]);
   const servicePath = systemdPath();
   if (existsSync(servicePath)) rmSync(servicePath, { force: true });
-  await run("systemctl", ["--user", "daemon-reload"], { capture: true, allowFailure: true });
+  await serviceRun("systemctl", ["--user", "daemon-reload"]);
   logger.info?.(`Autostart removed: ${servicePath}`);
   return { ok: true, provider: "systemd", path: servicePath };
 }
 
 async function statusSystemd() {
   const servicePath = systemdPath();
-  const result = await run("systemctl", ["--user", "status", "machine-bridge-mcp.service", "--no-pager"], { capture: true, allowFailure: true });
+  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 };
 }
 
@@ -216,19 +235,19 @@ WantedBy=default.target
 
 async function installWindowsTask(spec, logger) {
   const command = windowsCommand(spec);
-  const result = await run("schtasks", ["/Create", "/TN", WINDOWS_TASK, "/SC", "ONLOGON", "/TR", command, "/F"], { capture: true, allowFailure: true });
+  const result = await serviceRun("schtasks", ["/Create", "/TN", WINDOWS_TASK, "/SC", "ONLOGON", "/TR", command, "/F"]);
   logger.info?.("Windows Scheduled Task installed for logon");
   return { ok: result.code === 0, provider: "schtasks", task: WINDOWS_TASK, result };
 }
 
 async function uninstallWindowsTask(logger) {
-  const result = await run("schtasks", ["/Delete", "/TN", WINDOWS_TASK, "/F"], { capture: true, allowFailure: true });
+  const result = await serviceRun("schtasks", ["/Delete", "/TN", WINDOWS_TASK, "/F"]);
   logger.info?.("Windows Scheduled Task removed");
   return { ok: result.code === 0 || /cannot find/i.test(result.stderr), provider: "schtasks", task: WINDOWS_TASK, result };
 }
 
 async function statusWindowsTask() {
-  const result = await run("schtasks", ["/Query", "/TN", WINDOWS_TASK, "/FO", "LIST"], { capture: true, allowFailure: true });
+  const result = await serviceRun("schtasks", ["/Query", "/TN", WINDOWS_TASK, "/FO", "LIST"]);
   return { ok: result.code === 0, provider: "schtasks", installed: result.code === 0, task: WINDOWS_TASK, active: result.code === 0, detail: result.stdout || result.stderr };
 }