u-foo 2.4.9 → 2.4.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "2.4.9",
+  "version": "2.4.10",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",

package/src/runtime/contracts/eventContract.js

@@ -19,6 +19,7 @@ const IPC_REQUEST_TYPES = {
   AGENT_READY: "agent_ready",
   AGENT_REPORT: "agent_report",
   ASSIGN_ROLE: "assign_role",
+  REFRESH_STATUS: "refresh_status",
 };
 
 const IPC_RESPONSE_TYPES = {

package/src/runtime/daemon/controlPlaneService.js

@@ -0,0 +1,330 @@
+"use strict";
+
+const crypto = require("crypto");
+const net = require("net");
+const EventBus = require("../../coordination/bus");
+const { normalizeReportInput } = require("../../coordination/report/store");
+const { enqueueAgentReport } = require("./reportControlBus");
+const { isRunning, socketPath } = require("./index");
+const { IPC_REQUEST_TYPES } = require("../contracts/eventContract");
+const {
+  applyProjectNicknamePrefix,
+  checkAndCleanupNickname,
+} = require("./nicknameScope");
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeBusAgentType(agentType = "") {
+  const value = String(agentType || "").trim().toLowerCase();
+  if (!value) return "mcp-agent";
+  if (value === "claude") return "claude-code";
+  if (value === "ucode" || value === "ufoo") return "ufoo-code";
+  return value;
+}
+
+function ensureBusLoaded(projectRoot) {
+  const bus = new EventBus(projectRoot);
+  bus.ensureBus();
+  bus.loadBusData();
+  return bus;
+}
+
+function assertSubscriberExists(bus, subscriber) {
+  const meta = bus.subscriberManager.getSubscriber(subscriber);
+  if (!meta) {
+    const err = new Error(`subscriber not found: ${subscriber}`);
+    err.code = "subscriber_not_found";
+    throw err;
+  }
+  return meta;
+}
+
+function resolveSubscriberArg(args = {}) {
+  const subscriber = String(args.subscriber || args.source || "").trim();
+  if (!subscriber) {
+    const err = new Error("subscriber is required");
+    err.code = "invalid_subscriber";
+    throw err;
+  }
+  return subscriber;
+}
+
+function createSessionId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function createCryptoSessionId() {
+  return crypto.randomBytes(4).toString("hex");
+}
+
+function notifyDaemonRefresh(projectRoot) {
+  if (!isRunning(projectRoot)) return;
+  const sock = socketPath(projectRoot);
+  try {
+    const client = net.createConnection(sock, () => {
+      client.write(`${JSON.stringify({ type: IPC_REQUEST_TYPES.REFRESH_STATUS })}\n`);
+      client.end();
+    });
+    client.on("error", () => {});
+  } catch {
+    // fire-and-forget
+  }
+}
+
+async function registerAgentFull(projectRoot, args = {}, options = {}) {
+  const {
+    validateParentPid = false,
+    checkNicknameConflicts = false,
+  } = options;
+
+  const agentType = normalizeBusAgentType(args.agent_type || args.agentType || "mcp-agent");
+  const nickname = String(args.nickname || "").trim();
+  const launchMode = String(args.launch_mode || args.launchMode || "mcp").trim();
+  const capabilities = args.capabilities && typeof args.capabilities === "object"
+    ? args.capabilities
+    : null;
+  const hostCapabilities = args.hostCapabilities && typeof args.hostCapabilities === "object"
+    ? args.hostCapabilities
+    : capabilities;
+
+  // Session ID: explicit > reuse > generate
+  let sessionId;
+  const explicitSessionId = String(args.session_id || args.sessionId || "").trim();
+  const reuseSession = args.reuseSession && typeof args.reuseSession === "object"
+    ? args.reuseSession
+    : null;
+  const reuseSessionId = typeof reuseSession?.sessionId === "string"
+    ? reuseSession.sessionId.trim() : "";
+  const reuseSubscriberId = typeof reuseSession?.subscriberId === "string"
+    ? reuseSession.subscriberId.trim() : "";
+  const reuseProviderSessionId = typeof reuseSession?.providerSessionId === "string"
+    ? reuseSession.providerSessionId.trim() : "";
+
+  if (explicitSessionId) {
+    sessionId = explicitSessionId;
+  } else if (reuseSessionId && reuseSubscriberId === `${agentType}:${reuseSessionId}`) {
+    sessionId = reuseSessionId;
+  } else {
+    sessionId = validateParentPid ? createCryptoSessionId() : createSessionId();
+  }
+
+  // parentPid validation
+  const parentPid = Number.parseInt(args.parentPid, 10);
+  if (validateParentPid) {
+    if (!Number.isFinite(parentPid) || parentPid <= 0) {
+      const err = new Error("register_agent requires valid parentPid");
+      err.code = "invalid_parent_pid";
+      throw err;
+    }
+  }
+
+  // Nickname scope and conflict check
+  let finalNickname = nickname;
+  let scopedNickname = nickname
+    ? applyProjectNicknamePrefix(projectRoot, nickname, { agentType })
+    : "";
+  if (checkNicknameConflicts && finalNickname) {
+    const nickCheck = checkAndCleanupNickname(projectRoot, finalNickname, {
+      tty: String(args.tty || ""),
+      agentType,
+      scopedNickname,
+    });
+    if (nickCheck.existing) {
+      finalNickname = "";
+      scopedNickname = "";
+    }
+  }
+
+  // Bus join
+  const joinOptions = {
+    parentPid: Number.isFinite(parentPid) && parentPid > 0 ? parentPid : process.pid,
+    launchMode,
+    tmuxPane: String(args.tmuxPane || ""),
+    tty: String(args.tty || ""),
+    hostInjectSock: String(args.hostInjectSock || ""),
+    hostDaemonSock: String(args.hostDaemonSock || ""),
+    hostName: String(args.host_name || args.hostName || "ufoo-mcp"),
+    hostSessionId: String(args.hostSessionId || `mcp-${process.pid}`),
+    hostCapabilities: hostCapabilities,
+    scopedNickname: scopedNickname || String(args.scoped_nickname || args.scopedNickname || finalNickname || "").trim(),
+  };
+  if (args.skipSessionResolve) joinOptions.skipSessionResolve = true;
+  if (reuseSessionId) joinOptions.reuseSessionId = reuseSessionId;
+  if (reuseProviderSessionId) joinOptions.reuseProviderSessionId = reuseProviderSessionId;
+
+  const bus = ensureBusLoaded(projectRoot);
+  const result = await bus.subscriberManager.join(sessionId, agentType, finalNickname, joinOptions);
+  const subscriber = result.subscriber;
+  if (finalNickname) {
+    bus.subscriberManager.rename(subscriber, finalNickname, "ufoo-agent", { scopedNickname });
+  }
+  const meta = bus.subscriberManager.getSubscriber(subscriber) || {};
+  meta.activity_state = String(args.activity_state || "ready");
+  meta.activity_since = nowIso();
+  meta.mcp_bridge = !validateParentPid;
+  if (hostCapabilities) meta.mcp_capabilities = hostCapabilities;
+  bus.saveBusData();
+  notifyDaemonRefresh(projectRoot);
+  return {
+    ok: true,
+    project_root: projectRoot,
+    subscriber_id: subscriber,
+    subscriber,
+    session_id: sessionId,
+    agent_type: agentType,
+    nickname: meta.nickname || result.nickname || finalNickname || "",
+    scoped_nickname: meta.scoped_nickname || result.scopedNickname || scopedNickname || "",
+    launch_mode: launchMode,
+    reuseProviderSessionId,
+    skipSessionResolve: !!args.skipSessionResolve,
+  };
+}
+
+async function registerAgent(projectRoot, args = {}) {
+  return registerAgentFull(projectRoot, args, {
+    validateParentPid: false,
+    checkNicknameConflicts: false,
+  });
+}
+
+async function heartbeatAgent(projectRoot, args = {}) {
+  const subscriber = resolveSubscriberArg(args);
+  const bus = ensureBusLoaded(projectRoot);
+  const meta = assertSubscriberExists(bus, subscriber);
+  bus.subscriberManager.updateLastSeen(subscriber);
+  meta.status = "active";
+  bus.saveBusData();
+  notifyDaemonRefresh(projectRoot);
+  return {
+    ok: true,
+    project_root: projectRoot,
+    subscriber,
+    last_seen: meta.last_seen,
+  };
+}
+
+async function publishActivityState(projectRoot, args = {}) {
+  const subscriber = resolveSubscriberArg(args);
+  const activityState = String(args.activity_state || args.activityState || "").trim();
+  if (!activityState) {
+    const err = new Error("activity_state is required");
+    err.code = "invalid_activity_state";
+    throw err;
+  }
+  const bus = ensureBusLoaded(projectRoot);
+  const meta = assertSubscriberExists(bus, subscriber);
+  bus.subscriberManager.updateLastSeen(subscriber);
+  meta.status = "active";
+  meta.activity_state = activityState;
+  meta.activity_detail = String(args.detail || "").trim();
+  meta.activity_since = String(args.since || "").trim() || nowIso();
+  bus.saveBusData();
+  notifyDaemonRefresh(projectRoot);
+  return {
+    ok: true,
+    project_root: projectRoot,
+    subscriber,
+    activity_state: meta.activity_state,
+    activity_detail: meta.activity_detail,
+    activity_since: meta.activity_since,
+  };
+}
+
+async function updateAgentMetadata(projectRoot, args = {}) {
+  const subscriber = resolveSubscriberArg(args);
+  const bus = ensureBusLoaded(projectRoot);
+  const meta = assertSubscriberExists(bus, subscriber);
+  const nickname = String(args.nickname || "").trim();
+  if (nickname) {
+    await bus.subscriberManager.rename(subscriber, nickname);
+  }
+  const metadata = args.metadata && typeof args.metadata === "object" ? args.metadata : {};
+  if (Object.keys(metadata).length > 0) {
+    meta.mcp_metadata = {
+      ...(meta.mcp_metadata && typeof meta.mcp_metadata === "object" ? meta.mcp_metadata : {}),
+      ...metadata,
+    };
+  }
+  bus.subscriberManager.updateLastSeen(subscriber);
+  bus.saveBusData();
+  notifyDaemonRefresh(projectRoot);
+  const nextMeta = bus.subscriberManager.getSubscriber(subscriber) || meta;
+  return {
+    ok: true,
+    project_root: projectRoot,
+    subscriber,
+    nickname: nextMeta.nickname || "",
+    scoped_nickname: nextMeta.scoped_nickname || nextMeta.nickname || "",
+    metadata: nextMeta.mcp_metadata || {},
+  };
+}
+
+async function pollInbox(projectRoot, args = {}) {
+  const subscriber = resolveSubscriberArg(args);
+  const limit = Number.isFinite(Number(args.limit)) && Number(args.limit) > 0
+    ? Math.floor(Number(args.limit))
+    : 50;
+  const bus = ensureBusLoaded(projectRoot);
+  assertSubscriberExists(bus, subscriber);
+  bus.subscriberManager.updateLastSeen(subscriber);
+  bus.saveBusData();
+  const pending = await bus.messageManager.check(subscriber);
+  return {
+    ok: true,
+    project_root: projectRoot,
+    subscriber,
+    count: pending.length,
+    messages: pending.slice(0, limit),
+    truncated: pending.length > limit,
+  };
+}
+
+async function reportAgentStatus(projectRoot, args = {}) {
+  const subscriber = resolveSubscriberArg(args);
+  const report = normalizeReportInput({
+    ...args,
+    agent_id: subscriber,
+    source: "mcp",
+  });
+  const queued = await enqueueAgentReport(projectRoot, report, { publisher: subscriber });
+  return {
+    ok: true,
+    project_root: projectRoot,
+    status: "queued",
+    request_id: queued.request_id,
+    report,
+    queued,
+  };
+}
+
+async function unregisterAgent(projectRoot, args = {}) {
+  const subscriber = resolveSubscriberArg(args);
+  const bus = ensureBusLoaded(projectRoot);
+  const ok = await bus.subscriberManager.leave(subscriber);
+  bus.saveBusData();
+  notifyDaemonRefresh(projectRoot);
+  return {
+    ok,
+    project_root: projectRoot,
+    subscriber,
+  };
+}
+
+module.exports = {
+  normalizeBusAgentType,
+  ensureBusLoaded,
+  assertSubscriberExists,
+  resolveSubscriberArg,
+  createSessionId,
+  notifyDaemonRefresh,
+  registerAgentFull,
+  registerAgent,
+  heartbeatAgent,
+  publishActivityState,
+  updateAgentMetadata,
+  pollInbox,
+  reportAgentStatus,
+  unregisterAgent,
+};

package/src/runtime/daemon/index.js

@@ -40,6 +40,7 @@ const {
   applyProjectNicknamePrefix,
   resolveDisplayNickname,
   resolveScopedNickname,
+  checkAndCleanupNickname,
 } = require("./nicknameScope");
 const { resolveNodeExecutable } = require("../process/nodeExecutable");
 
@@ -474,57 +475,6 @@ async function waitForNewSubscriber(projectRoot, agentType, existing, timeoutMs
   return null;
 }
 
-function checkAndCleanupNickname(projectRoot, nickname, { tty = "", agentType = "", scopedNickname = "" } = {}) {
-  const conflictNickname = scopedNickname || applyProjectNicknamePrefix(projectRoot, nickname, {
-    agentType,
-    force: true,
-  });
-  if (!conflictNickname) return { existing: null, cleaned: false };
-  const busPath = getUfooPaths(projectRoot).agentsFile;
-  try {
-    const bus = JSON.parse(fs.readFileSync(busPath, "utf8"));
-    const entries = Object.entries(bus.agents || {})
-      .filter(([, meta]) => {
-        const candidate = resolveScopedNickname(projectRoot, meta);
-        return meta && candidate === conflictNickname;
-      });
-
-    if (entries.length === 0) {
-      return { existing: null, cleaned: false };
-    }
-
-    // Check for active agent with same nickname
-    const activeAgent = entries.find(([, meta]) => meta.status === "active");
-    if (activeAgent) {
-      const [existingId, existingMeta] = activeAgent;
-      // Allow takeover when the existing holder is a pre-registered stub
-      // (same agent type, no TTY) or occupies the same TTY — the new
-      // registration is the real agent replacing the placeholder.
-      const sameType = agentType && existingMeta.agent_type === agentType;
-      // A stub is a pre-registered entry with no TTY AND no meaningful activity
-      // state. Internal-mode agents also lack a TTY but will have activity_state
-      // set once they start working — don't evict those.
-      const isStub = sameType && !existingMeta.tty && !existingMeta.activity_state;
-      const sameTty = tty && existingMeta.tty === tty;
-      if (isStub || sameTty) {
-        delete bus.agents[existingId];
-        fs.writeFileSync(busPath, JSON.stringify(bus, null, 2));
-        return { existing: null, cleaned: true };
-      }
-      return { existing: existingId, cleaned: false };
-    }
-
-    // Clean up offline agents with same nickname
-    for (const [agentId] of entries) {
-      delete bus.agents[agentId];
-    }
-    fs.writeFileSync(busPath, JSON.stringify(bus, null, 2));
-    return { existing: null, cleaned: true };
-  } catch {
-    return { existing: null, cleaned: false };
-  }
-}
-
 function resolveSubscriberNickname(projectRoot, subscriberId) {
   if (!subscriberId) return "";
   try {
@@ -2331,19 +2281,10 @@ function startDaemon({ projectRoot, provider, model, resumeMode = "auto" }) {
       return;
     }
     if (req.type === IPC_REQUEST_TYPES.REGISTER_AGENT) {
-      // Manual agent launch requests daemon to register it
       const {
         agentType,
         nickname,
         parentPid,
-        launchMode,
-        tmuxPane,
-        tty,
-        hostInjectSock,
-        hostDaemonSock,
-        hostName,
-        hostSessionId,
-        hostCapabilities,
         skipSessionResolve,
       } = req;
       if (!agentType) {
@@ -2357,85 +2298,22 @@ function startDaemon({ projectRoot, provider, model, resumeMode = "auto" }) {
         return;
       }
       try {
-        const crypto = require("crypto");
-        const requestedReuse = req.reuseSession && typeof req.reuseSession === "object"
-          ? req.reuseSession
-          : null;
-        const reuseSessionId = typeof requestedReuse?.sessionId === "string"
-          ? requestedReuse.sessionId.trim()
-          : "";
-        const reuseSubscriberId = typeof requestedReuse?.subscriberId === "string"
-          ? requestedReuse.subscriberId.trim()
-          : "";
-        const reuseProviderSessionId = typeof requestedReuse?.providerSessionId === "string"
-          ? requestedReuse.providerSessionId.trim()
-          : "";
-
-        let sessionId = crypto.randomBytes(4).toString("hex");
-        let subscriberId = `${agentType}:${sessionId}`;
-        if (reuseSessionId && reuseSubscriberId === `${agentType}:${reuseSessionId}`) {
-          sessionId = reuseSessionId;
-          subscriberId = reuseSubscriberId;
-        } else if (reuseSessionId || reuseSubscriberId) {
-          log(`register_agent ignored invalid reuseSession for ${agentType}`);
-        }
-
-        // Daemon registers the agent in bus
-        const eventBus = new EventBus(projectRoot);
-        await eventBus.init();
-        eventBus.loadBusData();
-        const parsedParentPid = Number.parseInt(parentPid, 10);
-        if (!Number.isFinite(parsedParentPid) || parsedParentPid <= 0) {
-          throw new Error("register_agent requires valid parentPid");
-        }
-        const joinOptions = {
-          parentPid: Number.isFinite(parsedParentPid) ? parsedParentPid : undefined,
-          launchMode: launchMode || "",
-          tmuxPane: tmuxPane || "",
-          tty: tty || "",
-          hostInjectSock: hostInjectSock || "",
-          hostDaemonSock: hostDaemonSock || "",
-          hostName: hostName || "",
-          hostSessionId: hostSessionId || "",
-          hostCapabilities: hostCapabilities && typeof hostCapabilities === "object"
-            ? hostCapabilities
-            : null,
-          reuseSessionId,
-          reuseProviderSessionId,
-        };
-        if (skipSessionResolve) joinOptions.skipSessionResolve = true;
-
-        let finalNickname = nickname || "";
-        let scopedNickname = applyProjectNicknamePrefix(projectRoot, finalNickname, {
-          agentType: normalizeBusAgentType(agentType),
+        const controlPlane = require("./controlPlaneService");
+        const result = await controlPlane.registerAgentFull(projectRoot, {
+          ...req,
+          agent_type: agentType,
+          parentPid,
+        }, {
+          validateParentPid: true,
+          checkNicknameConflicts: true,
         });
-        if (finalNickname) {
-          const nickCheck = checkAndCleanupNickname(projectRoot, finalNickname, {
-            tty: tty || "",
-            agentType: normalizeBusAgentType(agentType),
-            scopedNickname,
-          });
-          if (nickCheck.existing) {
-            finalNickname = "";
-            scopedNickname = "";
-          }
-        }
-        await eventBus.join(
-          sessionId,
-          normalizeBusAgentType(agentType),
-          finalNickname,
-          { ...joinOptions, scopedNickname },
-        );
-        if (finalNickname) {
-          eventBus.rename(subscriberId, finalNickname, "ufoo-agent", { scopedNickname });
-        }
-        eventBus.saveBusData();
-        const resolvedNickname = resolveSubscriberNickname(projectRoot, subscriberId) || finalNickname || "";
+        const subscriberId = result.subscriber;
+        const resolvedNickname = resolveSubscriberNickname(projectRoot, subscriberId) || result.nickname || "";
 
-        if (!skipSessionResolve && reuseProviderSessionId) {
+        if (!skipSessionResolve && result.reuseProviderSessionId) {
           if (providerSessions) {
             providerSessions.set(subscriberId, {
-              sessionId: reuseProviderSessionId,
+              sessionId: result.reuseProviderSessionId,
               source: "reuse",
               updated_at: new Date().toISOString(),
             });
@@ -2547,6 +2425,12 @@ function startDaemon({ projectRoot, provider, model, resumeMode = "auto" }) {
       tryResolveSession(1);
       return;
     }
+    if (req.type === IPC_REQUEST_TYPES.REFRESH_STATUS) {
+      cleanupInactiveSubscribers();
+      const status = buildRuntimeStatus();
+      ipcServer.sendToSockets({ type: IPC_RESPONSE_TYPES.STATUS, data: status });
+      return;
+    }
   };
 
   ipcServer.listen(socketPath(projectRoot));

package/src/runtime/daemon/mcpServer.js

@@ -5,11 +5,9 @@ const net = require("net");
 const path = require("path");
 const { spawn } = require("child_process");
 
-const EventBus = require("../../coordination/bus");
 const { getUfooPaths } = require("../../coordination/state/paths");
-const { normalizeReportInput } = require("../../coordination/report/store");
-const { enqueueAgentReport } = require("./reportControlBus");
 const { isRunning, socketPath } = require("./index");
+const controlPlane = require("./controlPlaneService");
 const {
   normalizeProjectRoot,
   resolveGlobalControllerProjectRoot,
@@ -171,18 +169,6 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
   },
 ]);
 
-function normalizeBusAgentType(agentType = "") {
-  const value = String(agentType || "").trim().toLowerCase();
-  if (!value) return "mcp-agent";
-  if (value === "claude") return "claude-code";
-  if (value === "ucode" || value === "ufoo") return "ufoo-code";
-  return value;
-}
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
 function cloneJson(value) {
   return JSON.parse(JSON.stringify(value || {}));
 }
@@ -286,10 +272,6 @@ async function suppressConsoleToStderr(fn) {
   }
 }
 
-function createSessionId() {
-  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-}
-
 function listRegisteredProjectRows() {
   return listProjectRuntimes({ validate: true, cleanupTmp: true })
     .filter((row) => !isGlobalControllerProjectRoot(row && row.project_root));
@@ -315,33 +297,6 @@ function resolveRegisteredProjectRoot(args = {}, options = {}) {
   return match.project_root || normalized;
 }
 
-function ensureBusLoaded(projectRoot) {
-  const bus = new EventBus(projectRoot);
-  bus.ensureBus();
-  bus.loadBusData();
-  return bus;
-}
-
-function assertSubscriberExists(bus, subscriber) {
-  const meta = bus.subscriberManager.getSubscriber(subscriber);
-  if (!meta) {
-    const err = new Error(`subscriber not found: ${subscriber}`);
-    err.code = "subscriber_not_found";
-    throw err;
-  }
-  return meta;
-}
-
-function resolveSubscriberArg(args = {}) {
-  const subscriber = String(args.subscriber || args.source || "").trim();
-  if (!subscriber) {
-    const err = new Error("subscriber is required");
-    err.code = "invalid_subscriber";
-    throw err;
-  }
-  return subscriber;
-}
-
 function connectSocket(sockPath, timeoutMs = 500) {
   return new Promise((resolve, reject) => {
     let timer = null;
@@ -438,165 +393,37 @@ async function handleMcpStatus(ctx = {}) {
 
 async function handleRegisterAgent(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  const agentType = normalizeBusAgentType(args.agent_type || args.agentType || "mcp-agent");
-  const sessionId = String(args.session_id || args.sessionId || createSessionId()).trim();
-  const nickname = String(args.nickname || "").trim();
-  const launchMode = String(args.launch_mode || args.launchMode || "mcp").trim();
-  const capabilities = args.capabilities && typeof args.capabilities === "object"
-    ? args.capabilities
-    : null;
-  const bus = ensureBusLoaded(projectRoot);
-  const result = await bus.subscriberManager.join(sessionId, agentType, nickname, {
-    parentPid: process.pid,
-    launchMode,
-    scopedNickname: String(args.scoped_nickname || args.scopedNickname || nickname || "").trim(),
-    hostName: "ufoo-mcp",
-    hostSessionId: `mcp-${process.pid}`,
-    hostCapabilities: capabilities,
-  });
-  const subscriber = result.subscriber;
-  const meta = bus.subscriberManager.getSubscriber(subscriber) || {};
-  meta.activity_state = String(args.activity_state || "ready");
-  meta.activity_since = nowIso();
-  meta.mcp_bridge = true;
-  if (capabilities) meta.mcp_capabilities = capabilities;
-  bus.saveBusData();
-  return {
-    ok: true,
-    project_root: projectRoot,
-    subscriber_id: subscriber,
-    subscriber,
-    session_id: sessionId,
-    agent_type: agentType,
-    nickname: meta.nickname || result.nickname || "",
-    scoped_nickname: meta.scoped_nickname || result.scopedNickname || "",
-    launch_mode: launchMode,
-  };
+  return controlPlane.registerAgent(projectRoot, args);
 }
 
 async function handleHeartbeatAgent(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  const subscriber = resolveSubscriberArg(args);
-  const bus = ensureBusLoaded(projectRoot);
-  const meta = assertSubscriberExists(bus, subscriber);
-  bus.subscriberManager.updateLastSeen(subscriber);
-  meta.status = "active";
-  bus.saveBusData();
-  return {
-    ok: true,
-    project_root: projectRoot,
-    subscriber,
-    last_seen: meta.last_seen,
-  };
+  return controlPlane.heartbeatAgent(projectRoot, args);
 }
 
 async function handlePublishActivityState(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  const subscriber = resolveSubscriberArg(args);
-  const activityState = String(args.activity_state || args.activityState || "").trim();
-  if (!activityState) {
-    const err = new Error("activity_state is required");
-    err.code = "invalid_activity_state";
-    throw err;
-  }
-  const bus = ensureBusLoaded(projectRoot);
-  const meta = assertSubscriberExists(bus, subscriber);
-  bus.subscriberManager.updateLastSeen(subscriber);
-  meta.status = "active";
-  meta.activity_state = activityState;
-  meta.activity_detail = String(args.detail || "").trim();
-  meta.activity_since = String(args.since || "").trim() || nowIso();
-  bus.saveBusData();
-  return {
-    ok: true,
-    project_root: projectRoot,
-    subscriber,
-    activity_state: meta.activity_state,
-    activity_detail: meta.activity_detail,
-    activity_since: meta.activity_since,
-  };
+  return controlPlane.publishActivityState(projectRoot, args);
 }
 
 async function handleUpdateAgentMetadata(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  const subscriber = resolveSubscriberArg(args);
-  const bus = ensureBusLoaded(projectRoot);
-  const meta = assertSubscriberExists(bus, subscriber);
-  const nickname = String(args.nickname || "").trim();
-  if (nickname) {
-    await bus.subscriberManager.rename(subscriber, nickname);
-  }
-  const metadata = args.metadata && typeof args.metadata === "object" ? args.metadata : {};
-  if (Object.keys(metadata).length > 0) {
-    meta.mcp_metadata = {
-      ...(meta.mcp_metadata && typeof meta.mcp_metadata === "object" ? meta.mcp_metadata : {}),
-      ...metadata,
-    };
-  }
-  bus.subscriberManager.updateLastSeen(subscriber);
-  bus.saveBusData();
-  const nextMeta = bus.subscriberManager.getSubscriber(subscriber) || meta;
-  return {
-    ok: true,
-    project_root: projectRoot,
-    subscriber,
-    nickname: nextMeta.nickname || "",
-    scoped_nickname: nextMeta.scoped_nickname || nextMeta.nickname || "",
-    metadata: nextMeta.mcp_metadata || {},
-  };
+  return controlPlane.updateAgentMetadata(projectRoot, args);
 }
 
 async function handlePollInbox(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  const subscriber = resolveSubscriberArg(args);
-  const limit = Number.isFinite(Number(args.limit)) && Number(args.limit) > 0
-    ? Math.floor(Number(args.limit))
-    : 50;
-  const bus = ensureBusLoaded(projectRoot);
-  assertSubscriberExists(bus, subscriber);
-  bus.subscriberManager.updateLastSeen(subscriber);
-  bus.saveBusData();
-  const pending = await bus.messageManager.check(subscriber);
-  return {
-    ok: true,
-    project_root: projectRoot,
-    subscriber,
-    count: pending.length,
-    messages: pending.slice(0, limit),
-    truncated: pending.length > limit,
-  };
+  return controlPlane.pollInbox(projectRoot, args);
 }
 
 async function handleReportAgentStatus(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  const subscriber = resolveSubscriberArg(args);
-  const report = normalizeReportInput({
-    ...args,
-    agent_id: subscriber,
-    source: "mcp",
-  });
-  const queued = await enqueueAgentReport(projectRoot, report, { publisher: subscriber });
-  return {
-    ok: true,
-    project_root: projectRoot,
-    status: "queued",
-    request_id: queued.request_id,
-    report,
-    queued,
-  };
+  return controlPlane.reportAgentStatus(projectRoot, args);
 }
 
 async function handleUnregisterAgent(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
-  const subscriber = resolveSubscriberArg(args);
-  const bus = ensureBusLoaded(projectRoot);
-  const ok = await bus.subscriberManager.leave(subscriber);
-  bus.saveBusData();
-  return {
-    ok,
-    project_root: projectRoot,
-    subscriber,
-  };
+  return controlPlane.unregisterAgent(projectRoot, args);
 }
 
 function findCustomTool(name) {
@@ -643,6 +470,7 @@ class UfooMcpServer {
     };
     this.initialized = false;
     this.startup = null;
+    this.registeredSubscribers = [];
   }
 
   async ensureStarted() {
@@ -717,6 +545,17 @@ class UfooMcpServer {
           ...this.options,
           toolCallId: id,
         }));
+        if (name === "register_agent" && result && result.subscriber && result.project_root) {
+          this.registeredSubscribers.push({
+            subscriber: result.subscriber,
+            projectRoot: result.project_root,
+          });
+        }
+        if (name === "unregister_agent" && result && result.subscriber) {
+          this.registeredSubscribers = this.registeredSubscribers.filter(
+            (entry) => entry.subscriber !== result.subscriber
+          );
+        }
         return createJsonRpcResult(id, createMcpContent(result));
       }
 
@@ -729,6 +568,17 @@ class UfooMcpServer {
       return createJsonRpcError(id, MCP_ERROR_CODES.INTERNAL_ERROR, err.message || String(err), data);
     }
   }
+
+  cleanup() {
+    for (const { subscriber, projectRoot } of this.registeredSubscribers) {
+      try {
+        controlPlane.unregisterAgent(projectRoot, { subscriber });
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    this.registeredSubscribers = [];
+  }
 }
 
 function createUfooMcpServer(options = {}) {
@@ -772,6 +622,9 @@ async function runMcpServer(options = {}) {
     }
   });
 
+  input.on("end", () => server.cleanup());
+  input.on("close", () => server.cleanup());
+
   return server;
 }
 

package/src/runtime/daemon/nicknameScope.js

@@ -2,6 +2,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const { getUfooPaths } = require("../../coordination/state/paths");
 
 function asTrimmedString(value) {
   if (typeof value !== "string") return "";
@@ -109,6 +110,49 @@ function resolveScopedNickname(projectRoot, meta = {}, fallback = "") {
   return applyProjectNicknamePrefix(projectRoot, fallbackValue, { force: true });
 }
 
+function checkAndCleanupNickname(projectRoot, nickname, { tty = "", agentType = "", scopedNickname = "" } = {}) {
+  const conflictNickname = scopedNickname || applyProjectNicknamePrefix(projectRoot, nickname, {
+    agentType,
+    force: true,
+  });
+  if (!conflictNickname) return { existing: null, cleaned: false };
+  const busPath = getUfooPaths(projectRoot).agentsFile;
+  try {
+    const bus = JSON.parse(fs.readFileSync(busPath, "utf8"));
+    const entries = Object.entries(bus.agents || {})
+      .filter(([, meta]) => {
+        const candidate = resolveScopedNickname(projectRoot, meta);
+        return meta && candidate === conflictNickname;
+      });
+
+    if (entries.length === 0) {
+      return { existing: null, cleaned: false };
+    }
+
+    const activeAgent = entries.find(([, meta]) => meta.status === "active");
+    if (activeAgent) {
+      const [existingId, existingMeta] = activeAgent;
+      const sameType = agentType && existingMeta.agent_type === agentType;
+      const isStub = sameType && !existingMeta.tty && !existingMeta.activity_state;
+      const sameTty = tty && existingMeta.tty === tty;
+      if (isStub || sameTty) {
+        delete bus.agents[existingId];
+        fs.writeFileSync(busPath, JSON.stringify(bus, null, 2));
+        return { existing: null, cleaned: true };
+      }
+      return { existing: existingId, cleaned: false };
+    }
+
+    for (const [agentId] of entries) {
+      delete bus.agents[agentId];
+    }
+    fs.writeFileSync(busPath, JSON.stringify(bus, null, 2));
+    return { existing: null, cleaned: true };
+  } catch {
+    return { existing: null, cleaned: false };
+  }
+}
+
 module.exports = {
   normalizeNicknameSegment,
   buildProjectNicknamePrefix,
@@ -117,4 +161,5 @@ module.exports = {
   stripProjectNicknamePrefix,
   resolveDisplayNickname,
   resolveScopedNickname,
+  checkAndCleanupNickname,
 };