machine-bridge-mcp 0.10.0 → 0.11.1

package/src/local/agent-context.mjs

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, opendir, realpath, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createBuiltinInstruction, discoverAutomaticProjectInstruction } from "./default-instructions.mjs";
 
 const CONFIG_RELATIVE_PATH = join(".machine-bridge", "agent.json");
 const GLOBAL_CONFIG_RELATIVE_PATH = join(".config", "machine-bridge-mcp", "agent.json");
@@ -23,7 +24,7 @@ const MAX_COMMAND_ARGV = 128;
 const MAX_COMMAND_ARGUMENT_BYTES = 256 * 1024;
 const COMMAND_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
 const TOKEN_STOP_WORDS = new Set(["the", "and", "for", "with", "from", "this", "that", "use", "using", "into", "of", "to", "a", "an", "in", "on", "is", "are", "or", "及", "和", "的", "了", "在", "用", "使用", "进行", "根据"]);
-const CONFIG_KEYS = new Set(["version", "model_instructions_file", "instruction_files", "instruction_max_bytes", "skill_roots", "commands"]);
+const CONFIG_KEYS = new Set(["version", "builtin_instructions", "automatic_project_context", "model_instructions_file", "instruction_files", "instruction_max_bytes", "skill_roots", "commands"]);
 const COMMAND_KEYS = new Set(["description", "argv", "cwd", "timeout_seconds", "allow_extra_args"]);
 
 export class AgentContextManager {
@@ -46,8 +47,10 @@ export class AgentContextManager {
     const result = {
       target: this.displayPath(state.target),
       scope_root: this.displayPath(state.scopeRoot),
-      precedence: "global guidance first, then scope root to target directory; each directory contributes the first non-empty instruction_files candidate; later directories have higher precedence",
+      precedence: "built-in defaults, automatic project facts, user-global guidance, then scope root to target directory; explicit files loaded later have higher precedence",
       config_files: state.configFiles.map((file) => this.displayPath(file)),
+      builtin_instructions: publicVirtualInstruction(state.builtinInstructions, includeContent),
+      automatic_project_context: publicVirtualInstruction(state.automaticProjectContext, includeContent),
       model_instructions_file: state.modelInstructions ? {
         path: this.displayPath(state.modelInstructions.path),
         bytes: state.modelInstructions.bytes,
@@ -68,12 +71,13 @@ export class AgentContextManager {
       instructions_truncated: state.instructionsTruncated,
       commands: publicCommands(state.commands, this.displayPath),
       guidance: [
+        "Apply built-in instructions and automatic project context as lower-precedence defaults; explicit global/project instruction files loaded later take precedence.",
         "Treat instruction_files as authoritative workspace guidance in the returned precedence order.",
         "Load a relevant skill with load_local_skill before following its workflow; SKILL.md is an instruction bundle, not executable code by itself.",
         "Prefer run_local_command for registered repeatable commands. Use run_process or exec_command only when no registered command fits and policy permits it.",
       ],
     };
-    if (includeContent) result.effective_instructions = renderEffectiveInstructions([...(state.modelInstructions ? [state.modelInstructions] : []), ...state.instructions], this.displayPath);
+    if (includeContent) result.effective_instructions = renderEffectiveInstructions(effectiveInstructionItems(state), this.displayPath);
     return result;
   }
 
@@ -83,7 +87,9 @@ export class AgentContextManager {
     const fingerprint = capabilityFingerprint(state, []);
     return {
       target: this.displayPath(state.target),
-      instructions: renderEffectiveInstructions([...(state.modelInstructions ? [state.modelInstructions] : []), ...state.instructions], this.displayPath),
+      instructions: renderEffectiveInstructions(effectiveInstructionItems(state), this.displayPath),
+      builtin_instructions: publicVirtualInstruction(state.builtinInstructions, false),
+      automatic_project_context: publicVirtualInstruction(state.automaticProjectContext, false),
       model_instructions_file: state.modelInstructions ? this.displayPath(state.modelInstructions.path) : null,
       capability_refresh: {
         strategy: "resolve_task_capabilities-rescans-on-every-call",
@@ -92,6 +98,7 @@ export class AgentContextManager {
         generated_at: new Date().toISOString(),
       },
       guidance: [
+        "Built-in working agreements and bounded automatic project facts are present by default unless disabled in the user-global agent config.",
         "Call resolve_task_capabilities with the current user task before substantive local work or at the start of a reused-host conversation.",
         "The resolver returns the effective instructions again and rescans skill and command metadata on every call; the runtime supplements application and browser capability metadata.",
       ],
@@ -125,7 +132,9 @@ export class AgentContextManager {
     return {
       task,
       target: this.displayPath(state.target),
-      effective_instructions: renderEffectiveInstructions([...(state.modelInstructions ? [state.modelInstructions] : []), ...state.instructions], this.displayPath),
+      effective_instructions: renderEffectiveInstructions(effectiveInstructionItems(state), this.displayPath),
+      builtin_instructions: publicVirtualInstruction(state.builtinInstructions, false),
+      automatic_project_context: publicVirtualInstruction(state.automaticProjectContext, false),
       model_instructions_file: state.modelInstructions ? this.displayPath(state.modelInstructions.path) : null,
       instruction_files: state.instructions.map((item) => ({ path: this.displayPath(item.path), scope: item.scope, bytes: item.bytes, sha256: item.sha256, precedence: item.precedence })),
       instructions_truncated: state.instructionsTruncated,
@@ -232,6 +241,10 @@ export class AgentContextManager {
       instructionMaxBytes: DEFAULT_INSTRUCTION_MAX_BYTES,
       skillRoots: defaultSkillRoots(directories, this.home, this.policy.unrestrictedPaths === true),
       commands: new Map(),
+      builtinInstructionsEnabled: true,
+      automaticProjectContextEnabled: true,
+      builtinInstructions: null,
+      automaticProjectContext: null,
       modelInstructionsFile: "",
       modelInstructions: null,
       configFiles: [],
@@ -247,9 +260,22 @@ export class AgentContextManager {
         if (this.policy.unrestrictedPaths === true) this.applyConfig(state, config, globalConfig, this.home, { global: true });
         else {
           state.configFiles.push(globalConfig);
+          if (config.builtinInstructions !== null) state.builtinInstructionsEnabled = config.builtinInstructions;
+          if (config.automaticProjectContext !== null) state.automaticProjectContextEnabled = config.automaticProjectContext;
           if (config.modelInstructionsFile) state.modelInstructionsFile = resolveConfiguredPath(config.modelInstructionsFile, this.home, this.home, this.workspace, true);
         }
       }
+    }
+
+    state.builtinInstructions = createBuiltinInstruction(state.builtinInstructionsEnabled);
+    state.automaticProjectContext = await discoverAutomaticProjectInstruction({
+      scopeRoot,
+      targetDir,
+      enabled: state.automaticProjectContextEnabled,
+      throwIfCancelled: () => this.throwIfCancelled(context),
+    });
+
+    if (this.home) {
       if (state.modelInstructionsFile) await this.collectModelInstructions(state, context);
       if (this.policy.unrestrictedPaths === true && this.codexHome) await this.collectDirectoryInstruction(state, this.codexHome, context, "global");
     }
@@ -266,6 +292,14 @@ export class AgentContextManager {
 
   applyConfig(state, config, configPath, baseDir, { global = false } = {}) {
     state.configFiles.push(configPath);
+    if (config.builtinInstructions !== null) {
+      if (!global) throw new Error(`builtin_instructions is only allowed in the global agent config: ${configPath}`);
+      state.builtinInstructionsEnabled = config.builtinInstructions;
+    }
+    if (config.automaticProjectContext !== null) {
+      if (!global) throw new Error(`automatic_project_context is only allowed in the global agent config: ${configPath}`);
+      state.automaticProjectContextEnabled = config.automaticProjectContext;
+    }
     if (config.modelInstructionsFile) {
       if (!global) throw new Error(`model_instructions_file is only allowed in the global agent config: ${configPath}`);
       state.modelInstructionsFile = resolveConfiguredPath(config.modelInstructionsFile, baseDir, this.home, this.workspace, true);
@@ -480,7 +514,23 @@ function normalizeConfig(value, configPath) {
   if (!isPlainRecord(value)) throw new Error(`agent config must be a JSON object: ${configPath}`);
   for (const key of Object.keys(value)) if (!CONFIG_KEYS.has(key)) throw new Error(`unknown agent config field '${key}': ${configPath}`);
   if (value.version !== 1) throw new Error(`agent config version must be 1: ${configPath}`);
-  const result = { modelInstructionsFile: null, instructionFiles: null, instructionMaxBytes: null, skillRoots: null, commands: new Map() };
+  const result = {
+    builtinInstructions: null,
+    automaticProjectContext: null,
+    modelInstructionsFile: null,
+    instructionFiles: null,
+    instructionMaxBytes: null,
+    skillRoots: null,
+    commands: new Map(),
+  };
+  if (value.builtin_instructions !== undefined) {
+    if (typeof value.builtin_instructions !== "boolean") throw new Error(`builtin_instructions must be boolean: ${configPath}`);
+    result.builtinInstructions = value.builtin_instructions;
+  }
+  if (value.automatic_project_context !== undefined) {
+    if (typeof value.automatic_project_context !== "boolean") throw new Error(`automatic_project_context must be boolean: ${configPath}`);
+    result.automaticProjectContext = value.automatic_project_context;
+  }
   if (value.model_instructions_file !== undefined) {
     result.modelInstructionsFile = requiredString(value.model_instructions_file, "model_instructions_file");
   }
@@ -657,7 +707,12 @@ async function listSkillFiles(root, maxFiles, context, throwIfCancelled) {
 function capabilityFingerprint(state, skills) {
   return sha256(JSON.stringify({
     configs: state.configFiles,
-    instructions: [state.modelInstructions?.sha256 || "", ...state.instructions.map((item) => item.sha256)],
+    instructions: [
+      state.builtinInstructions?.sha256 || "",
+      state.automaticProjectContext?.sha256 || "",
+      state.modelInstructions?.sha256 || "",
+      ...state.instructions.map((item) => item.sha256),
+    ],
     skills: skills.map((skill) => [skill.id, skill.sha256]),
     commands: [...state.commands.values()].map((command) => [command.name, command.argv]),
   }));
@@ -763,12 +818,36 @@ function publicCommands(commands, displayPath) {
     }));
 }
 
+function effectiveInstructionItems(state) {
+  return [
+    ...(state.builtinInstructions ? [state.builtinInstructions] : []),
+    ...(state.automaticProjectContext ? [state.automaticProjectContext] : []),
+    ...(state.modelInstructions ? [state.modelInstructions] : []),
+    ...state.instructions,
+  ];
+}
+
+function publicVirtualInstruction(item, includeContent) {
+  if (!item) return null;
+  return {
+    source: item.source,
+    scope: item.scope,
+    bytes: item.bytes,
+    sha256: item.sha256,
+    precedence: item.precedence,
+    ...(includeContent ? { content: item.content } : {}),
+  };
+}
+
 function renderEffectiveInstructions(instructions, displayPath) {
-  return instructions.map((item) => [
-    `--- BEGIN ${displayPath(item.path)} (precedence ${item.precedence}) ---`,
-    item.content,
-    `--- END ${displayPath(item.path)} ---`,
-  ].join("\n")).join("\n\n");
+  return instructions.map((item) => {
+    const source = item.source || displayPath(item.path);
+    return [
+      `--- BEGIN ${source} (precedence ${item.precedence}) ---`,
+      item.content,
+      `--- END ${source} ---`,
+    ].join("\n");
+  }).join("\n\n");
 }
 
 async function readOptionalRegularUtf8(filePath, maxBytes, label) {

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";
@@ -144,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);
@@ -320,8 +321,15 @@ async function startCommand(args) {
   }
 
   try {
-    await prepareStartMode(args, state, logger);
-    const daemonLock = acquireDaemonLock(state);
+    const startMode = await prepareStartMode(args, state, logger);
+    const daemonLock = await acquireDaemonLockWithTakeover(state, {
+      takeOverServiceOwner: startMode.takeOverServiceOwner,
+      ownerMetadata: {
+        mode: args.daemonOnly ? "service" : "foreground",
+        version: currentPackageVersion(),
+      },
+      logger,
+    });
     if (!daemonLock.acquired) {
       reportExistingDaemon(args, state, daemonLock.owner, logger);
       return;
@@ -336,11 +344,13 @@ async function prepareStartMode(args, state, logger) {
   if (args.daemonOnly) {
     const { trimAutostartLogs } = await import("./service.mjs");
     trimAutostartLogs(state.paths.stateRoot);
-    return;
+    return { takeOverServiceOwner: false };
   }
-  // Stop an installed service before acquiring the runtime lock. If a
-  // foreground daemon owns the lock, no new policy or secret state is saved.
-  await stopAutostartBestEffort(logger);
+  // 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);
 }
 
 function reportExistingDaemon(args, state, owner, logger) {
@@ -349,21 +359,24 @@ function reportExistingDaemon(args, state, owner, logger) {
     logger.debug?.("local daemon already running; daemon-only start completed as an idempotent no-op", { owner_pid_known: Boolean(owner?.pid) });
     return;
   }
-  logger.warn(`local daemon already running for this workspace (${pid}); requested changes were not applied`);
+  const mode = owner?.mode === "foreground" ? "foreground" : owner?.mode === "service" ? "background service" : "local";
+  const version = owner?.version ? `, version ${owner.version}` : "";
+  const notice = `${mode} daemon already running for this workspace (${pid}${version}); it was not restarted and requested changes were not applied`;
+  logger.warn(notice);
   if (args.json) {
     printStartJson(state, {
       showCredentials: Boolean((args.printMcpCredentials || args.printCredentials) && !args.noPrintCredentials),
       requestedChangesApplied: false,
-      notice: "local daemon already running; requested changes were not applied",
+      notice,
     });
     return;
   }
-  printMcpConnection(state, {
-    noPrintCredentials: Boolean(args.noPrintCredentials),
-    includeCredentials: Boolean(args.printMcpCredentials || args.printCredentials),
-    quiet: Boolean(args.quiet),
-    verbose: Boolean(args.verbose),
-  });
+  if (owner?.mode === "foreground") {
+    logger.plain("  Stop the existing foreground process with Ctrl+C in its terminal, then retry.");
+  } else {
+    logger.plain("  Run `machine-mcp service stop`, verify `machine-mcp service status`, then retry.");
+  }
+  logger.plain(`  Workspace: ${state.workspace.path}`);
 }
 
 function isIdempotentDaemonOnlyStart(args) {
@@ -1202,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") {
@@ -1222,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");
@@ -1246,12 +1297,19 @@ async function installAutostartBestEffort({ workspace, stateRoot, entryScript, l
 }
 
 async function stopAutostartBestEffort(logger) {
+  let result = null;
   try {
     const { stopAutostart } = await import("./service.mjs");
-    await stopAutostart({ logger: structuredLogger(true) });
+    result = await stopAutostart({ logger: structuredLogger(true) });
   } catch (error) {
-    logger.warn("Autostart stop skipped", { error_class: classifyOperationalError(error) });
+    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) {
@@ -1433,7 +1491,7 @@ Usage:
   .\\mbm.cmd                                      # from source checkout on Windows cmd
 
 Commands:
-  start             Deploy/update Worker, install autostart, start remote daemon
+  start             Deploy/update Worker, take over autostart, run foreground daemon
   stdio             Run a local MCP stdio server for Claude, Cursor, Codex, and compatible clients
   client-config     Print stdio client configuration snippets
   workspace show    Show remembered workspace

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));
+}