u-foo 3.0.18 → 3.0.19

package/src/runtime/daemon/controlPlaneService.js

@@ -22,6 +22,8 @@ const WAIT_FOR_MESSAGE_DEFAULT_TIMEOUT_SECONDS = 600;
 const WAIT_FOR_MESSAGE_MAX_TIMEOUT_SECONDS = 600;
 const WAIT_FOR_MESSAGE_POLL_INTERVAL_MS = 1000;
 const WAIT_FOR_MESSAGE_HEARTBEAT_INTERVAL_MS = 15000;
+const MCP_AGENT_LEASE_TTL_MS = 24 * 60 * 60 * 1000;
+const MCP_AGENT_RECENT_HEARTBEAT_MS = 30 * 1000;
 
 function nowIso() {
   return new Date().toISOString();
@@ -70,6 +72,61 @@ function createCryptoSessionId() {
   return crypto.randomBytes(4).toString("hex");
 }
 
+function createAgentHandle() {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+function hashAgentHandle(handle = "") {
+  return crypto.createHash("sha256").update(String(handle || ""), "utf8").digest("hex");
+}
+
+function leaseExpiryIso(nowMs = Date.now()) {
+  return new Date(nowMs + MCP_AGENT_LEASE_TTL_MS).toISOString();
+}
+
+function extendMcpAgentLease(meta, nowMs = Date.now()) {
+  meta.mcp_lease_expires_at = leaseExpiryIso(nowMs);
+  delete meta.mcp_revoked_at;
+  return meta.mcp_lease_expires_at;
+}
+
+function assertAgentHandle(bus, subscriber, args = {}, options = {}) {
+  const meta = assertSubscriberExists(bus, subscriber);
+  if (meta.mcp_bridge !== true || !meta.mcp_agent_handle_hash) {
+    const err = new Error(`subscriber is not an MCP-registered Agent: ${subscriber}`);
+    err.code = "agent_handle_not_available";
+    throw err;
+  }
+  const handle = String(args.agent_handle || args.agentHandle || "").trim();
+  if (!handle) {
+    const err = new Error("agent_handle is required");
+    err.code = "agent_handle_required";
+    throw err;
+  }
+  const actual = Buffer.from(hashAgentHandle(handle), "hex");
+  const expected = Buffer.from(String(meta.mcp_agent_handle_hash || ""), "hex");
+  if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) {
+    const err = new Error("agent_handle does not own this subscriber");
+    err.code = "invalid_agent_handle";
+    throw err;
+  }
+  if (options.allowInactive !== true && meta.status !== "active") {
+    const err = new Error(`Agent registration is inactive: ${subscriber}`);
+    err.code = "agent_lease_inactive";
+    throw err;
+  }
+  const expiresAtMs = Date.parse(String(meta.mcp_lease_expires_at || ""));
+  if (
+    options.allowExpired !== true
+    && (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now())
+  ) {
+    const err = new Error(`Agent lease expired: ${subscriber}`);
+    err.code = "agent_lease_expired";
+    throw err;
+  }
+  return meta;
+}
+
 function notifyDaemonRefresh(projectRoot) {
   if (!isRunning(projectRoot)) return;
   const sock = socketPath(projectRoot);
@@ -99,6 +156,10 @@ async function registerAgentFull(projectRoot, args = {}, options = {}) {
   const hostCapabilities = args.hostCapabilities && typeof args.hostCapabilities === "object"
     ? args.hostCapabilities
     : capabilities;
+  const clientInstanceId = String(
+    args.client_instance_id || args.clientInstanceId || ""
+  ).trim();
+  const bus = ensureBusLoaded(projectRoot);
 
   // Session ID: explicit > reuse > generate
   let sessionId;
@@ -113,7 +174,22 @@ async function registerAgentFull(projectRoot, args = {}, options = {}) {
   const reuseProviderSessionId = typeof reuseSession?.providerSessionId === "string"
     ? reuseSession.providerSessionId.trim() : "";
 
-  if (explicitSessionId) {
+  const recoveredEntry = !validateParentPid && clientInstanceId
+    ? Object.entries(bus.busData.agents || {}).find(([, meta]) => (
+      meta
+      && meta.mcp_bridge === true
+      && meta.agent_type === agentType
+      && meta.mcp_client_instance_id === clientInstanceId
+    ))
+    : null;
+  const recoveredSubscriber = recoveredEntry ? recoveredEntry[0] : "";
+  const recoveredSessionId = recoveredSubscriber.startsWith(`${agentType}:`)
+    ? recoveredSubscriber.slice(agentType.length + 1)
+    : "";
+
+  if (recoveredSessionId) {
+    sessionId = recoveredSessionId;
+  } else if (explicitSessionId) {
     sessionId = explicitSessionId;
   } else if (reuseSessionId && reuseSubscriberId === `${agentType}:${reuseSessionId}`) {
     sessionId = reuseSessionId;
@@ -165,7 +241,18 @@ async function registerAgentFull(projectRoot, args = {}, options = {}) {
   if (reuseSessionId) joinOptions.reuseSessionId = reuseSessionId;
   if (reuseProviderSessionId) joinOptions.reuseProviderSessionId = reuseProviderSessionId;
 
-  const bus = ensureBusLoaded(projectRoot);
+  const candidateSubscriber = `${agentType}:${sessionId}`;
+  const existingCandidate = bus.subscriberManager.getSubscriber(candidateSubscriber);
+  if (
+    !validateParentPid
+    && existingCandidate
+    && existingCandidate.mcp_agent_handle_hash
+    && (!clientInstanceId || existingCandidate.mcp_client_instance_id !== clientInstanceId)
+  ) {
+    const err = new Error(`subscriber is already registered: ${candidateSubscriber}`);
+    err.code = "subscriber_already_registered";
+    throw err;
+  }
   const result = await bus.subscriberManager.join(sessionId, agentType, finalNickname, joinOptions);
   const subscriber = result.subscriber;
   if (finalNickname) {
@@ -175,6 +262,14 @@ async function registerAgentFull(projectRoot, args = {}, options = {}) {
   meta.activity_state = String(args.activity_state || "ready");
   meta.activity_since = nowIso();
   meta.mcp_bridge = !validateParentPid;
+  let agentHandle = "";
+  if (!validateParentPid) {
+    agentHandle = createAgentHandle();
+    meta.mcp_agent_handle_hash = hashAgentHandle(agentHandle);
+    meta.mcp_client_instance_id = clientInstanceId;
+    meta.mcp_registered_at = meta.mcp_registered_at || nowIso();
+    extendMcpAgentLease(meta);
+  }
   if (hostCapabilities) meta.mcp_capabilities = hostCapabilities;
   bus.saveBusData();
   notifyDaemonRefresh(projectRoot);
@@ -188,6 +283,12 @@ async function registerAgentFull(projectRoot, args = {}, options = {}) {
     nickname: meta.nickname || result.nickname || finalNickname || "",
     scoped_nickname: meta.scoped_nickname || result.scopedNickname || scopedNickname || "",
     launch_mode: launchMode,
+    ...(agentHandle ? {
+      agent_handle: agentHandle,
+      lease_expires_at: meta.mcp_lease_expires_at,
+      client_instance_id: clientInstanceId,
+      recovered: Boolean(recoveredSubscriber),
+    } : {}),
     reuseProviderSessionId,
     skipSessionResolve: !!args.skipSessionResolve,
   };
@@ -203,9 +304,10 @@ async function registerAgent(projectRoot, args = {}) {
 async function heartbeatAgent(projectRoot, args = {}) {
   const subscriber = resolveSubscriberArg(args);
   const bus = ensureBusLoaded(projectRoot);
-  const meta = assertSubscriberExists(bus, subscriber);
+  const meta = assertAgentHandle(bus, subscriber, args);
   bus.subscriberManager.updateLastSeen(subscriber);
   meta.status = "active";
+  const leaseExpiresAt = extendMcpAgentLease(meta);
   bus.saveBusData();
   notifyDaemonRefresh(projectRoot);
   return {
@@ -213,6 +315,7 @@ async function heartbeatAgent(projectRoot, args = {}) {
     project_root: projectRoot,
     subscriber,
     last_seen: meta.last_seen,
+    lease_expires_at: leaseExpiresAt,
   };
 }
 
@@ -225,7 +328,7 @@ async function publishActivityState(projectRoot, args = {}) {
     throw err;
   }
   const bus = ensureBusLoaded(projectRoot);
-  const meta = assertSubscriberExists(bus, subscriber);
+  const meta = assertAgentHandle(bus, subscriber, args);
   bus.subscriberManager.updateLastSeen(subscriber);
   meta.status = "active";
   meta.activity_state = activityState;
@@ -246,7 +349,7 @@ async function publishActivityState(projectRoot, args = {}) {
 async function updateAgentMetadata(projectRoot, args = {}) {
   const subscriber = resolveSubscriberArg(args);
   const bus = ensureBusLoaded(projectRoot);
-  const meta = assertSubscriberExists(bus, subscriber);
+  const meta = assertAgentHandle(bus, subscriber, args);
   const nickname = String(args.nickname || "").trim();
   if (nickname) {
     await bus.subscriberManager.rename(subscriber, nickname);
@@ -278,7 +381,7 @@ async function pollInbox(projectRoot, args = {}) {
     ? Math.floor(Number(args.limit))
     : 50;
   const bus = ensureBusLoaded(projectRoot);
-  assertSubscriberExists(bus, subscriber);
+  assertAgentHandle(bus, subscriber, args);
   bus.subscriberManager.updateLastSeen(subscriber);
   bus.saveBusData();
   const pending = await bus.messageManager.check(subscriber);
@@ -365,14 +468,15 @@ function eventSeq(event = {}) {
   return Number.isInteger(seq) && seq > 0 ? seq : 0;
 }
 
-function touchWaitingSubscriber(bus, subscriber) {
+function touchWaitingSubscriber(bus, subscriber, args = {}) {
   // Long waits span concurrent metadata updates from other agents. Reload
   // before writing heartbeat state so a stale in-memory registry cannot
   // overwrite those updates.
   bus.loadBusData();
-  const meta = assertSubscriberExists(bus, subscriber);
+  const meta = assertAgentHandle(bus, subscriber, args);
   meta.status = "active";
   bus.subscriberManager.updateLastSeen(subscriber);
+  extendMcpAgentLease(meta);
   bus.saveBusData();
 }
 
@@ -393,7 +497,7 @@ async function waitForMessage(projectRoot, args = {}, options = {}) {
   const timeoutMs = timeoutSeconds * 1000;
 
   const bus = ensureBusLoaded(projectRoot);
-  touchWaitingSubscriber(bus, subscriber);
+  touchWaitingSubscriber(bus, subscriber, args);
   const lease = acquirePollLease(path.join(
     bus.busDir,
     "pids",
@@ -418,7 +522,7 @@ async function waitForMessage(projectRoot, args = {}, options = {}) {
       if (unseen.length > 0) {
         const messages = unseen.slice(0, limit);
         const lastSeq = Math.max(afterSeq, ...messages.map(eventSeq));
-        touchWaitingSubscriber(bus, subscriber);
+        touchWaitingSubscriber(bus, subscriber, args);
         return {
           ok: true,
           project_root: projectRoot,
@@ -436,7 +540,7 @@ async function waitForMessage(projectRoot, args = {}, options = {}) {
 
       const current = now();
       if (current >= deadline) {
-        touchWaitingSubscriber(bus, subscriber);
+        touchWaitingSubscriber(bus, subscriber, args);
         return {
           ok: true,
           project_root: projectRoot,
@@ -453,7 +557,7 @@ async function waitForMessage(projectRoot, args = {}, options = {}) {
       }
 
       if (current >= nextHeartbeatAt) {
-        touchWaitingSubscriber(bus, subscriber);
+        touchWaitingSubscriber(bus, subscriber, args);
         nextHeartbeatAt = current + heartbeatIntervalMs;
       }
 
@@ -469,6 +573,8 @@ async function waitForMessage(projectRoot, args = {}, options = {}) {
 
 async function reportAgentStatus(projectRoot, args = {}) {
   const subscriber = resolveSubscriberArg(args);
+  const bus = ensureBusLoaded(projectRoot);
+  assertAgentHandle(bus, subscriber, args);
   const report = normalizeReportInput({
     ...args,
     agent_id: subscriber,
@@ -488,6 +594,12 @@ async function reportAgentStatus(projectRoot, args = {}) {
 async function unregisterAgent(projectRoot, args = {}) {
   const subscriber = resolveSubscriberArg(args);
   const bus = ensureBusLoaded(projectRoot);
+  const meta = assertAgentHandle(bus, subscriber, args, {
+    allowExpired: true,
+    allowInactive: true,
+  });
+  meta.mcp_revoked_at = nowIso();
+  meta.mcp_lease_expires_at = meta.mcp_revoked_at;
   const ok = await bus.subscriberManager.leave(subscriber);
   bus.saveBusData();
   notifyDaemonRefresh(projectRoot);
@@ -504,6 +616,10 @@ module.exports = {
   assertSubscriberExists,
   resolveSubscriberArg,
   createSessionId,
+  createAgentHandle,
+  hashAgentHandle,
+  assertAgentHandle,
+  extendMcpAgentLease,
   notifyDaemonRefresh,
   registerAgentFull,
   registerAgent,
@@ -517,4 +633,6 @@ module.exports = {
   normalizeWaitForMessageArgs,
   WAIT_FOR_MESSAGE_DEFAULT_TIMEOUT_SECONDS,
   WAIT_FOR_MESSAGE_MAX_TIMEOUT_SECONDS,
+  MCP_AGENT_LEASE_TTL_MS,
+  MCP_AGENT_RECENT_HEARTBEAT_MS,
 };

package/src/runtime/daemon/index.js

@@ -45,6 +45,10 @@ const {
   checkAndCleanupNickname,
 } = require("./nicknameScope");
 const { resolveNodeExecutable } = require("../process/nodeExecutable");
+const {
+  createProjectRuntimeControlPlane,
+} = require("./projectRuntimeControlPlane");
+const { loadConfig, normalizeMcpPort } = require("../../config");
 
 let providerSessions = null;
 let sessionResolveHandles = new Map();
@@ -1351,9 +1355,63 @@ function startDaemon({ projectRoot, provider, model, resumeMode = "auto" }) {
     },
   });
   deliveryScheduler.start();
+  const runtimeControlPlane = createProjectRuntimeControlPlane({ projectRoot });
+  let mcpHttpServer = null;
+  if (isGlobalControllerProjectRoot(projectRoot) && process.env.UFOO_MCP_HTTP_DISABLED !== "1") {
+    const { createGlobalMcpHttpServer } = require("./mcpHttpServer");
+    const config = loadConfig(projectRoot);
+    const configuredPort = process.env.UFOO_MCP_PORT || config.mcpPort;
+    mcpHttpServer = createGlobalMcpHttpServer({
+      projectRoot,
+      port: normalizeMcpPort(configuredPort),
+      log,
+    });
+    mcpHttpServer.start().catch((err) => {
+      logSync(`MCP HTTP startup failed: ${formatFatalReason(err)}`);
+      setImmediate(() => {
+        throw err;
+      });
+    });
+  }
 
   handleIpcRequest = async (req, socket) => {
     if (!req || typeof req !== "object") return;
+    if (await runtimeControlPlane.handleRequest(req, socket)) return;
+    if (req.type === IPC_REQUEST_TYPES.MCP_STATUS || req.type === IPC_REQUEST_TYPES.MCP_RESTART) {
+      if (!isGlobalControllerProjectRoot(projectRoot)) {
+        socket.write(`${JSON.stringify({
+          type: IPC_RESPONSE_TYPES.ERROR,
+          error: "MCP control is owned by the global controller daemon",
+        })}\n`);
+        return;
+      }
+      try {
+        if (req.type === IPC_REQUEST_TYPES.MCP_RESTART) {
+          if (!mcpHttpServer) {
+            throw new Error("MCP HTTP listener is disabled");
+          }
+          await mcpHttpServer.stop();
+          await mcpHttpServer.start();
+        }
+        socket.write(`${JSON.stringify({
+          type: IPC_RESPONSE_TYPES.RESPONSE,
+          data: {
+            ok: true,
+            operation: req.type === IPC_REQUEST_TYPES.MCP_RESTART ? "restart" : "status",
+            mcp: mcpHttpServer
+              ? mcpHttpServer.getStatus()
+              : { running: false, disabled: true },
+          },
+        })}\n`);
+      } catch (err) {
+        socket.write(`${JSON.stringify({
+          type: IPC_RESPONSE_TYPES.ERROR,
+          error: err.message || String(err),
+          code: err.code || "mcp_control_error",
+        })}\n`);
+      }
+      return;
+    }
     if (req.type === IPC_REQUEST_TYPES.STATUS) {
       cleanupInactiveSubscribers();
       const status = buildRuntimeStatus();
@@ -2595,6 +2653,13 @@ function startDaemon({ projectRoot, provider, model, resumeMode = "auto" }) {
     }
     daemonGroupOrchestrator = null;
 
+    runtimeControlPlane.stop();
+    if (mcpHttpServer) {
+      void mcpHttpServer.stop().catch((err) => {
+        writeLog(`MCP HTTP shutdown failed: ${formatFatalReason(err)}`);
+      });
+    }
+
     // 清理所有子进程
     processManager.cleanup();
 

package/src/runtime/daemon/mcpConfigure.js

@@ -0,0 +1,175 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const {
+  readConnectionFiles,
+} = require("./mcpStdioProxy");
+const {
+  resolveGlobalControllerProjectRoot,
+} = require("../projects");
+
+const MANAGED_BLOCK_START = "# >>> ufoo MCP (managed)";
+const MANAGED_BLOCK_END = "# <<< ufoo MCP (managed)";
+
+function tomlString(value = "") {
+  return JSON.stringify(String(value || ""));
+}
+
+function codexConfigPath(options = {}) {
+  if (options.configPath) return options.configPath;
+  const codexHome = String(options.codexHome || process.env.CODEX_HOME || "").trim();
+  return path.join(codexHome || path.join(os.homedir(), ".codex"), "config.toml");
+}
+
+function buildCodexManagedBlock(connection) {
+  return [
+    MANAGED_BLOCK_START,
+    "[mcp_servers.ufoo]",
+    `url = ${tomlString(connection.endpoint)}`,
+    `http_headers = { Authorization = ${tomlString(`Bearer ${connection.token}`)} }`,
+    "tool_timeout_sec = 610",
+    "enabled = true",
+    MANAGED_BLOCK_END,
+  ].join("\n");
+}
+
+function removeManagedBlock(text = "") {
+  const escapedStart = MANAGED_BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const escapedEnd = MANAGED_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return String(text || "").replace(
+    new RegExp(`(?:^|\\n)${escapedStart}\\n[\\s\\S]*?\\n${escapedEnd}(?=\\n|$)`, "g"),
+    ""
+  );
+}
+
+function findTomlSections(text = "") {
+  const sections = [];
+  const pattern = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/gm;
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    sections.push({
+      header: match[1].trim(),
+      start: match.index,
+      contentStart: pattern.lastIndex,
+    });
+  }
+  return sections.map((section, index) => ({
+    ...section,
+    end: index + 1 < sections.length ? sections[index + 1].start : text.length,
+  }));
+}
+
+function isUfooMainSection(header = "") {
+  return /^(?:mcp_servers\.ufoo|mcp_servers\."ufoo")$/.test(String(header || ""));
+}
+
+function isUfooStdioEnvSection(header = "") {
+  return /^(?:mcp_servers\.ufoo|mcp_servers\."ufoo")\.env$/.test(String(header || ""));
+}
+
+function removeLegacyUfooTransportSections(text = "") {
+  const sections = findTomlSections(text);
+  const ranges = sections
+    .filter((section) => isUfooMainSection(section.header) || isUfooStdioEnvSection(section.header))
+    .map((section) => [section.start, section.end])
+    .sort((a, b) => b[0] - a[0]);
+  let next = text;
+  for (const [start, end] of ranges) {
+    next = `${next.slice(0, start)}${next.slice(end)}`;
+  }
+  return next;
+}
+
+function renderCodexConfig(existing, connection) {
+  const withoutManaged = removeManagedBlock(existing);
+  const withoutLegacy = removeLegacyUfooTransportSections(withoutManaged);
+  const trimmed = withoutLegacy.trimEnd();
+  return `${trimmed ? `${trimmed}\n\n` : ""}${buildCodexManagedBlock(connection)}\n`;
+}
+
+function configureCodexMcp(options = {}) {
+  const projectRoot = options.projectRoot || resolveGlobalControllerProjectRoot();
+  const connection = options.connection || readConnectionFiles(projectRoot);
+  const target = codexConfigPath(options);
+  const existing = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  const next = renderCodexConfig(existing, connection);
+  if (options.dryRun === true) {
+    const redacted = renderCodexConfig(existing, {
+      ...connection,
+      token: "<redacted>",
+    });
+    return {
+      ok: true,
+      dry_run: true,
+      target,
+      transport: "streamable_http",
+      endpoint: connection.endpoint,
+      changed: next !== existing,
+      content: redacted,
+    };
+  }
+
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  let backup = "";
+  if (fs.existsSync(target) && next !== existing) {
+    backup = `${target}.ufoo-backup-${Date.now()}`;
+    fs.copyFileSync(target, backup);
+    try {
+      fs.chmodSync(backup, 0o600);
+    } catch {
+      // Best effort for filesystems without POSIX modes.
+    }
+  }
+  fs.writeFileSync(target, next, { encoding: "utf8", mode: 0o600 });
+  try {
+    fs.chmodSync(target, 0o600);
+  } catch {
+    // Best effort for filesystems without POSIX modes.
+  }
+  return {
+    ok: true,
+    dry_run: false,
+    target,
+    backup: backup || null,
+    transport: "streamable_http",
+    endpoint: connection.endpoint,
+    changed: next !== existing,
+  };
+}
+
+function runMcpConfigureCli(host, options = {}) {
+  const normalized = String(host || "").trim().toLowerCase();
+  if (normalized !== "codex") {
+    const err = new Error(
+      `Direct HTTP auto-configuration is verified only for Codex App/CLI/IDE; keep ${normalized || "this host"} on the stateless "ufoo mcp" stdio proxy`
+    );
+    err.code = "unsupported_mcp_host_config";
+    throw err;
+  }
+  const result = configureCodexMcp(options);
+  if (options.dryRun === true) {
+    process.stdout.write(result.content);
+  } else {
+    process.stdout.write(`Configured Codex MCP at ${result.target}\n`);
+    process.stdout.write(`Transport: Streamable HTTP ${result.endpoint}\n`);
+    if (result.backup) process.stdout.write(`Backup: ${result.backup}\n`);
+    process.stdout.write("Restart Codex App/CLI/IDE to load the shared MCP configuration.\n");
+  }
+  return result;
+}
+
+module.exports = {
+  MANAGED_BLOCK_END,
+  MANAGED_BLOCK_START,
+  buildCodexManagedBlock,
+  codexConfigPath,
+  configureCodexMcp,
+  findTomlSections,
+  removeLegacyUfooTransportSections,
+  removeManagedBlock,
+  renderCodexConfig,
+  runMcpConfigureCli,
+};

package/src/runtime/daemon/mcpControl.js

@@ -0,0 +1,123 @@
+"use strict";
+
+const net = require("net");
+
+const {
+  IPC_REQUEST_TYPES,
+  IPC_RESPONSE_TYPES,
+} = require("../contracts/eventContract");
+const {
+  isRunning,
+  socketPath,
+} = require("./index");
+const {
+  resolveGlobalControllerProjectRoot,
+} = require("../projects");
+
+function requestMcpControl(operation, options = {}) {
+  const projectRoot = options.projectRoot || resolveGlobalControllerProjectRoot();
+  const checkRunning = options.isRunning || isRunning;
+  const resolveSocketPath = options.socketPath || socketPath;
+  const connect = options.connect || ((target) => net.createConnection(target));
+  const requestType = operation === "restart"
+    ? IPC_REQUEST_TYPES.MCP_RESTART
+    : IPC_REQUEST_TYPES.MCP_STATUS;
+  if (!checkRunning(projectRoot)) {
+    const err = new Error("Global controller daemon is not running");
+    err.code = "global_daemon_not_running";
+    return Promise.reject(err);
+  }
+
+  return new Promise((resolve, reject) => {
+    const client = connect(resolveSocketPath(projectRoot));
+    let buffer = "";
+    let settled = false;
+    const timeoutMs = Number(options.timeoutMs) || 10000;
+    let timer = null;
+
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      client.removeAllListeners();
+      try {
+        client.end();
+      } catch {
+        // ignore
+      }
+    };
+    const finishResolve = (value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+    const finishReject = (err) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
+
+    timer = setTimeout(() => {
+      finishReject(Object.assign(new Error("MCP control request timed out"), {
+        code: "mcp_control_timeout",
+      }));
+    }, timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+
+    client.on("connect", () => {
+      client.write(`${JSON.stringify({ type: requestType })}\n`);
+    });
+    client.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const lines = buffer.split(/\r?\n/);
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        let response;
+        try {
+          response = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (response.type === IPC_RESPONSE_TYPES.ERROR) {
+          const err = new Error(response.error || "MCP control failed");
+          err.code = response.code || "mcp_control_error";
+          finishReject(err);
+          return;
+        }
+        if (response.type === IPC_RESPONSE_TYPES.RESPONSE && response.data?.mcp) {
+          finishResolve(response.data);
+          return;
+        }
+      }
+    });
+    client.once("error", finishReject);
+    client.once("close", () => {
+      finishReject(Object.assign(new Error("Global controller closed the MCP control request"), {
+        code: "mcp_control_closed",
+      }));
+    });
+  });
+}
+
+async function runMcpControlCli(operation, options = {}) {
+  const result = await requestMcpControl(operation, options);
+  if (options.json === true) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  }
+  const status = result.mcp || {};
+  process.stdout.write(`MCP ${status.running ? "running" : "stopped"}\n`);
+  if (status.endpoint) process.stdout.write(`Endpoint: ${status.endpoint}\n`);
+  if (status.pid) process.stdout.write(`PID: ${status.pid}\n`);
+  process.stdout.write(`Sessions: ${status.session_count || 0}\n`);
+  process.stdout.write(`Active requests: ${status.active_request_count || 0}\n`);
+  process.stdout.write(`Active waits: ${status.active_wait_count || 0}\n`);
+  return result;
+}
+
+module.exports = {
+  requestMcpControl,
+  runMcpControlCli,
+};