u-foo 3.0.18 → 3.0.20

package/OPTIONAL_SKILLS/ufoo-bus-poll/SKILL.md

@@ -31,9 +31,11 @@ the host's maximum pending-call window ends.
    ufoo wrapper already registered the Agent and direct injection is its receive
    path. Do not call MCP `register_agent` or arm a poll.
 2. When the variable is absent, reuse the exact subscriber already returned to
-   this session by MCP `register_agent`, or call `register_agent` once. Do not
-   call bare `ufoo bus join` or borrow another subscriber. Keep the returned
-   value as the external Agent's identity.
+   this session by MCP `register_agent` together with its `agent_handle`, or
+   call `register_agent` once. Pass a stable `client_instance_id` when the host
+   exposes one. Do not call bare `ufoo bus join` or borrow another subscriber.
+   Keep the returned pair as the external Agent's identity. Never expose the
+   handle in messages, reports, logs, or the Cursor listener terminal.
 3. Select the receive mechanism from the host App's actual wake capability,
    never from Agent type:
 
@@ -59,6 +61,7 @@ prints stdout. Keep the wait inside one foreground MCP tool call instead:
 
    - `project_root`: the registered project root
    - `subscriber`: the caller-owned MCP subscriber
+   - `agent_handle`: the opaque handle returned with that registration
    - `after_seq`: `0` for the first wait, then the last returned `last_seq`
    - `timeout_seconds`: `600`
 2. Leave that tool call pending. Do not background it and do not start
@@ -66,7 +69,7 @@ prints stdout. Keep the wait inside one foreground MCP tool call instead:
    not invoke the model or consume model tokens.
 3. If it returns `status: "message"`, handle every returned message, then call
    MCP `ack_bus` with `through_seq: <last_seq>`. This preserves messages that
-   arrived after the returned batch.
+   arrived after the returned batch. Include the same `agent_handle`.
 4. If it returns `status: "timeout"`, no message was received. If monitoring is
    still required, immediately call `wait_for_message` again with the same
    `after_seq`. The timeout return is the only periodic model wake.
@@ -127,6 +130,7 @@ For Cursor, handle every `[ufoo]<from:...>` event in the emitted batch.
 2. Acknowledge only after handling:
 
    - Codex App: MCP `ack_bus` with the returned `last_seq` as `through_seq`.
+     Include the caller-owned `agent_handle`.
    - Cursor: run the exact command printed by the stream:
 
    ```bash
@@ -136,8 +140,8 @@ For Cursor, handle every `[ufoo]<from:...>` event in the emitted batch.
    Preserve the sequence boundary so later messages stay pending.
 3. Reply only with a requested result, answer, blocker, or fact the sender
    needs. Use MCP `dispatch_message` with the same `project_root`,
-   caller-owned subscriber, sender ID as `target`, and substantive result as
-   `message`.
+   caller-owned subscriber and `agent_handle`, sender ID as `target`, and
+   substantive result as `message`.
 
 Do not reply to greetings, thanks, or acknowledgement-only messages. After
 sending, continue the current task. Keep the existing Cursor stream running, or

package/README.md

@@ -27,8 +27,8 @@ Package: [u-foo on npm](https://www.npmjs.com/package/u-foo)
 - Launch modes for internal, tmux, host, Terminal.app, and iTerm2 workflows.
 - Built-in group templates for launching and orchestrating multi-agent workflows.
 - `ucode`, a native ufoo coding-agent runtime.
-- `ufoo mcp`, a local global MCP bridge with pending-call bus wake for external
-  MCP-capable agents.
+- One loopback Streamable HTTP MCP server inside the home-scoped global
+  controller daemon, plus a disposable `ufoo mcp` stdio compatibility proxy.
 
 ## Requirements
 
@@ -58,7 +58,7 @@ Installed binaries:
 
 | Binary | Purpose |
 |---|---|
-| `ufoo` | Main CLI, chat dashboard, daemon, local global MCP bridge, groups, bus, context, memory, reports, and online helpers. |
+| `ufoo` | Main CLI, chat dashboard, daemons, global MCP server/proxy, groups, bus, context, memory, reports, and online helpers. |
 | `uclaude` | Claude Code wrapper with ufoo bootstrap and bus identity. |
 | `ucodex` | Codex wrapper with ufoo bootstrap and bus identity. |
 | `uagy` | Antigravity wrapper with ufoo bootstrap and bus identity. |
@@ -100,15 +100,27 @@ Use global chat mode to switch between registered projects:
 ufoo -g
 ```
 
-For MCP-capable clients, configure the global stdio bridge once:
+For Codex App, Codex CLI, and the Codex IDE extension, start global mode once
+and install the shared direct HTTP configuration:
+
+```bash
+ufoo -g
+ufoo mcp configure codex
+```
+
+The configuration points all three Codex surfaces at the same authenticated
+loopback endpoint. Restart the Codex surface after configuring it.
+
+For a host that has not been verified with direct HTTP, keep the compatible
+stdio configuration:
 
 ```bash
 ufoo mcp
 ```
 
-The MCP bridge connects to the home-scoped global controller daemon and routes
-project-scoped tools through the global project registry. It is not a separate
-per-project MCP server mode.
+This command is a stateless transport proxy into the same global server. It
+does not own Agent registrations or project state. Inspect or restart the
+singleton listener with `ufoo mcp status` and `ufoo mcp restart`.
 
 ## Runtime Model
 
@@ -122,10 +134,13 @@ ufoo / ufoo chat
   -> coordination bus/context/memory/history/report/state/status
   -> shared controller/worker tools and native ucode tools
 
-ufoo mcp
-  -> home-scoped global controller daemon
+Codex App / CLI / IDE -> Streamable HTTP --+
+ufoo mcp stdio proxy ----------------------+
+                                           -> home-scoped global controller daemon
+                                              (one MCP listener and tool router)
   -> ~/.ufoo/projects/runtime
-  -> selected project daemon for bus/report/activity state
+  -> ProjectRuntimeGateway
+  -> selected project daemon for bus/report/activity/wait state
 ```
 
 ### Agent Delivery Modes
@@ -140,7 +155,8 @@ inherited `UFOO_SUBSCRIBER_ID` before any helper terminal is started:
   or run a resident bus poll.
 - Externally hosted Agents have no wrapper-provided subscriber environment.
   They register themselves once through MCP `register_agent`, retain the
-  returned subscriber, and select the host App's native no-token wait:
+  returned subscriber plus opaque `agent_handle`, and select the host App's
+  native no-token wait:
   Codex App keeps MCP `wait_for_message` pending, while Cursor monitors
   `ufoo bus poll --follow` background output with `notify_on_output`.
 
@@ -237,14 +253,18 @@ ufoo skills list --optional
 ufoo skills install ufoo-bus-poll --target /path/to/that/agent/skills
 ```
 
-Register once through MCP `register_agent` and retain its returned subscriber.
+Register once through MCP `register_agent` and retain its returned subscriber
+and `agent_handle`. Include the handle in heartbeat, activity, send, receive,
+acknowledgement, report, and unregister calls. The handle is an ownership
+capability: do not send it to peers or print it in reports.
 
 - **Codex App:** call MCP `wait_for_message` in the foreground with
-  `after_seq: 0` and `timeout_seconds: 600`. The tool call stays pending inside
-  ufoo; a message returns immediately and wakes the task without shell stdout.
-  On timeout, re-arm with the same cursor. After handling a message response,
-  call MCP `ack_bus` with its `last_seq` as `through_seq`, then re-arm with that
-  `last_seq` when the Agent is idle again.
+  the registered subscriber and handle, `after_seq: 0`, and
+  `timeout_seconds: 600`. The tool call stays pending inside ufoo; a message
+  returns immediately and wakes the task without shell stdout. On timeout,
+  re-arm with the same cursor. After handling a message response, call MCP
+  `ack_bus` with the same handle and its `last_seq` as `through_seq`, then
+  re-arm with that `last_seq` when the Agent is idle again.
 - **Cursor:** bind the MCP subscriber and run
   `export UFOO_SUBSCRIBER_ID="<subscriber-id>"; exec ufoo bus poll
   "$UFOO_SUBSCRIBER_ID" --follow --interval 30` through the monitored

package/README.zh-CN.md

@@ -25,8 +25,8 @@ npm 包：[u-foo](https://www.npmjs.com/package/u-foo)
 - 支持 internal、tmux、host、Terminal.app、iTerm2 等启动模式。
 - 内置 group 模板，用于启动和编排多 Agent 工作流。
 - 提供原生 ufoo coding-agent 运行时 `ucode`。
-- 提供 `ufoo mcp` 本机 global MCP bridge，并用 pending tool call 唤醒支持
-  MCP 的外部 Agent。
+- home 级 global controller daemon 内提供唯一的本机 Streamable HTTP MCP
+  server；`ufoo mcp` 仅作为可随时销毁的 stdio 兼容代理。
 
 ## 环境要求
 
@@ -56,7 +56,7 @@ npm link
 
 | 命令 | 用途 |
 |---|---|
-| `ufoo` | 主 CLI、chat 仪表盘、daemon、本机 global MCP bridge、group、bus、context、memory、report 和 online helper。 |
+| `ufoo` | 主 CLI、chat 仪表盘、daemon、global MCP server/proxy、group、bus、context、memory、report 和 online helper。 |
 | `uclaude` | Claude Code 包装器，注入 ufoo bootstrap 和 bus 身份。 |
 | `ucodex` | Codex 包装器，注入 ufoo bootstrap 和 bus 身份。 |
 | `uagy` | Antigravity 包装器，注入 ufoo bootstrap 和 bus 身份。 |
@@ -98,14 +98,18 @@ ucode
 ufoo -g
 ```
 
-给支持 MCP 的客户端使用时，只需要配置一次全局 stdio bridge：
+Codex App、Codex CLI 和 Codex IDE extension 共用同一份配置。先启动一次
+global mode，再写入经过验证的直接 HTTP 配置：
 
 ```bash
-ufoo mcp
+ufoo -g
+ufoo mcp configure codex
 ```
 
-MCP bridge 会连接 home 级 global controller daemon，并通过全局项目 registry
-把项目级工具路由到对应项目 daemon。它不是每个项目单独部署一个 MCP server 的模式。
+重启 Codex surface 后即可使用。尚未验证直接 HTTP 的 host 继续配置
+`ufoo mcp`；该命令只是连接同一 global server 的无状态 stdio 代理，不拥有
+Agent 注册或项目状态。用 `ufoo mcp status` 检查唯一 listener，用
+`ufoo mcp restart` 只重启 listener。
 
 ## 运行模型
 
@@ -119,10 +123,13 @@ ufoo / ufoo chat
   -> coordination bus/context/memory/history/report/state/status
   -> shared controller/worker tools and native ucode tools
 
-ufoo mcp
-  -> home-scoped global controller daemon
+Codex App / CLI / IDE -> Streamable HTTP --+
+ufoo mcp stdio proxy ----------------------+
+                                           -> home-scoped global controller daemon
+  -> one MCP listener and tool router
   -> ~/.ufoo/projects/runtime
-  -> selected project daemon for bus/report/activity state
+  -> ProjectRuntimeGateway
+  -> selected project daemon for bus/report/activity/wait state
 ```
 
 ### Agent 消息投递模式
@@ -135,9 +142,10 @@ ufoo 支持两种 Agent 投递模式，只根据启动辅助 terminal 之前，
   注入端点，因此可以直接注入 bus 消息。这类 Agent 复用环境中的身份，
   不通过 MCP 重复注册，也不运行常驻 bus poll。
 - 外部 host 托管的 Agent 没有包装器提供的 subscriber 环境变量。它通过 MCP
-  `register_agent` 注册一次，保留返回的 subscriber，再选择宿主 App 原生的
-  无 token 等待方式：Codex App 挂起 MCP `wait_for_message`，Cursor 则用
-  `notify_on_output` 监控 `ufoo bus poll --follow` 的后台输出。
+  `register_agent` 注册一次，保留返回的 subscriber 和不透明
+  `agent_handle`，再选择宿主 App 原生的无 token 等待方式：Codex App 挂起
+  MCP `wait_for_message`，Cursor 则用 `notify_on_output` 监控
+  `ufoo bus poll --follow` 的后台输出。
 
 Agent 类型名和 subscriber 前缀只是路由元数据，不是能力判断条件。外部
 Cursor Agent 通过 MCP 注册后，可以在专用监听 terminal 内把返回的
@@ -225,13 +233,16 @@ ufoo skills list --optional
 ufoo skills install ufoo-bus-poll --target /path/to/that/agent/skills
 ```
 
-先通过 MCP `register_agent` 注册一次并保留返回的 subscriber。
+先通过 MCP `register_agent` 注册一次并保留返回的 subscriber 与
+`agent_handle`。heartbeat、activity、send、receive、ack、report 和
+unregister 都带上该 handle；它是所有权凭证，不应发送给其他 Agent，也不应
+写进 report。
 
-- **Codex App：**前台调用 MCP `wait_for_message`，首次使用
-  `after_seq: 0`、`timeout_seconds: 600`。工具调用在 ufoo 内保持 pending；
-  有消息立即返回并唤醒当前任务，不依赖 shell stdout。超时后用相同游标续挂；
-  处理消息后，用返回的 `last_seq` 作为 MCP `ack_bus.through_seq`，Agent
-  再次空闲时以该 `last_seq` 续挂。
+- **Codex App：**前台调用 MCP `wait_for_message`，传入注册所得 subscriber
+  和 handle，首次使用 `after_seq: 0`、`timeout_seconds: 600`。工具调用在
+  ufoo 内保持 pending；有消息立即返回并唤醒当前任务，不依赖 shell stdout。
+  超时后用相同游标续挂；处理消息后，用同一 handle 和返回的 `last_seq`
+  调用 MCP `ack_bus`，Agent 再次空闲时以该 `last_seq` 续挂。
 - **Cursor：**在 monitored background shell 中绑定 MCP subscriber，再运行
   `export UFOO_SUBSCRIBER_ID="<subscriber-id>"; exec ufoo bus poll
   "$UFOO_SUBSCRIBER_ID" --follow --interval 30`，设置

package/SKILLS/ufoo/SKILL.md

@@ -23,18 +23,21 @@ capabilities from the Agent type or subscriber prefix.
   `register_agent`, run `ufoo bus join`, or start `ufoo bus poll`; the wrapper
   and daemon deliver follow-ups by direct prompt injection.
 - If `UFOO_SUBSCRIBER_ID` is absent, the Agent is externally hosted. Reuse the
-  subscriber already returned to this session by MCP `register_agent`, or call
-  `register_agent` once if none exists. Keep that returned subscriber as the
-  session identity and invoke `$ufoo-bus-poll` to establish the receive path
-  using this host App's own no-token wait and self-wake primitive. A
+  subscriber and `agent_handle` already returned to this session, or call
+  MCP `register_agent` once if none exists. When the host
+  exposes a stable local session identifier, pass it as `client_instance_id`
+  so a transport restart can recover the subscriber and rotate the handle.
+  Keep the returned pair as session-local identity; never send or report the
+  handle to another Agent. Invoke `$ufoo-bus-poll` to establish the receive
+  path using this host App's own no-token wait and self-wake primitive. A
   Cursor-style dedicated listener terminal may export the returned value as
   `UFOO_SUBSCRIBER_ID` after registration so its CLI commands share the
   identity. That helper-local export does not change the already selected
   external delivery mode and must not be treated as wrapper evidence.
 
 In the sections below, `<subscriber-id>` means the wrapper-provided
-`UFOO_SUBSCRIBER_ID` or the subscriber returned by MCP, according to this
-branch.
+`UFOO_SUBSCRIBER_ID` or the subscriber returned by MCP. `<agent-handle>` means
+the opaque capability returned with an external MCP registration.
 
 ## Synchronize workspace state
 
@@ -60,20 +63,25 @@ Treat these prompt prefixes as work inputs:
 For each received bus task:
 
 1. Execute it immediately within the current authority.
-2. Acknowledge it only after handling:
+2. Acknowledge it only after handling. A wrapper-managed Agent uses:
 
    ```bash
    ufoo bus ack "<subscriber-id>"
    ```
 
+   An external Agent calls MCP `ack_bus` with `project_root`, `subscriber`,
+   `agent_handle: "<agent-handle>"`, and the delivered sequence boundary.
 3. Reply only with a requested answer, delegated result, or fact the sender
    needs to continue. Do not reply with greetings or bare acknowledgements.
-4. Emit a concise runtime report for delegated work:
+4. Emit a concise runtime report for delegated work. A wrapper-managed Agent
+   uses:
 
    ```bash
    ufoo report done "<summary>" --agent "<subscriber-id>"
    ```
 
+   An external Agent calls MCP `report_agent_status` with the same subscriber
+   and handle.
 After sending or broadcasting, continue the current task. Do not start an
 ad-hoc check or poll, sleep, or wait for a reply. A wrapper-managed Agent
 receives follow-ups by direct injection; an external Agent leaves its existing

package/SKILLS/ufoo-bus/SKILL.md

@@ -29,8 +29,11 @@ signal. Evaluate it before creating or mutating helper terminals:
   value. Do not call MCP `register_agent`, run `ufoo bus join`, or arm resident
   polling.
 - Absent: this is an externally hosted Agent. Reuse this session's
-  MCP-registered subscriber or call MCP `register_agent` exactly once. Keep the
-  returned value as `<subscriber-id>` for later MCP and CLI operations. Invoke
+  MCP-registered subscriber and `agent_handle`, or call MCP `register_agent`
+  exactly once. If the host exposes a stable local session id, pass it as
+  `client_instance_id`. Keep the returned pair as `<subscriber-id>` and
+  `<agent-handle>` for later MCP operations. Treat the handle as a private
+  capability: do not send, log, or report it. Invoke
   `$ufoo-bus-poll` once at session start to select the receive path supported
   by the host App. That skill may bind the subscriber as
   `UFOO_SUBSCRIBER_ID` inside a dedicated Cursor listener terminal after MCP
@@ -49,7 +52,8 @@ ufoo bus check "<subscriber-id>"
 ```
 
 For an external Agent, use MCP `poll_inbox` with its `project_root` and
-caller-owned `<subscriber-id>` only when an explicit manual check is required.
+caller-owned `<subscriber-id>` and `<agent-handle>` only when an explicit
+manual check is required.
 If `$ufoo-bus-poll` woke the session with an emitted pending batch, handle that
 batch directly. Do not run a second check for the same wake.
 
@@ -68,6 +72,7 @@ For every pending batch:
    pending. For a `$ufoo-bus-poll` wake, run the exact `ack --through <seq>`
    line printed by the Cursor stream. A Codex App wait returns `last_seq`; pass
    it to MCP `ack_bus` as `through_seq`.
+   Every external `ack_bus` call also includes the caller-owned `agent_handle`.
 4. Reply only when the sender requested an answer, delegated work whose result
    is needed, or needs a discovered blocker or fact.
 
@@ -92,9 +97,9 @@ ufoo bus broadcast "<substantive message>"
 ```
 
 For an external Agent, call MCP `dispatch_message` with its `project_root`,
-caller-owned `subscriber`, `target`, and `message`. Use target `*` for a
-broadcast. This preserves the registered sender identity instead of creating a
-CLI-side identity.
+caller-owned `subscriber`, `agent_handle`, `target`, and `message`. Use target
+`*` for a broadcast. This preserves the registered sender identity instead of
+creating a CLI-side identity.
 
 Target resolution order is exact ID, nickname, agent type, then `*`.
 
@@ -120,7 +125,8 @@ using the rules above and leave re-arming or stream lifecycle to
 
 ## Report delegated work
 
-Use the shared report contract when bus work represents a task:
+Use the shared report contract when bus work represents a task. A
+wrapper-managed Agent uses:
 
 ```bash
 ufoo report start "<task>" --task <id> --agent "<subscriber-id>"
@@ -130,3 +136,6 @@ ufoo report error "<reason>" --task <id> --agent "<subscriber-id>"
 ```
 
 Use `--scope private` only for helper-internal reports.
+
+An external Agent calls MCP `report_agent_status` with `project_root`,
+`subscriber`, `agent_handle`, the task id, phase, and summary.

package/bin/ufoo.js

@@ -14,16 +14,21 @@ function hasGlobalModeFlag(args = []) {
 }
 
 function printMcpHelp() {
-  console.log("Usage: ufoo mcp [options]");
+  console.log("Usage: ufoo mcp [status|restart|configure codex] [options]");
   console.log("");
-  console.log("Run the local global ufoo MCP bridge over stdio.");
+  console.log("Run the stdio compatibility proxy or control the global MCP listener.");
   console.log("");
   console.log("Options:");
   console.log("  --no-auto-start  Do not auto-start the home-scoped global controller daemon");
+  console.log("  --json           Print status or restart results as JSON");
+  console.log("  --dry-run        Print a sanitized Codex migration preview without writing it");
   console.log("  -h, --help       Display help for the MCP bridge command");
   console.log("");
   console.log("Notes:");
   console.log("  Configure MCP-capable clients with command: ufoo mcp");
+  console.log("  Inspect the singleton listener: ufoo mcp status");
+  console.log("  Restart only the listener: ufoo mcp restart");
+  console.log("  Configure Codex App/CLI/IDE: ufoo mcp configure codex");
   console.log("  Example without daemon auto-start: ufoo mcp --no-auto-start");
   console.log("  Human diagnostics are available in chat: /mcp status, /mcp tools, /mcp help");
 }
@@ -47,9 +52,18 @@ async function main() {
       printMcpHelp();
       return;
     }
-    await runMcpServer({
-      autoStart: !argv.includes("--no-auto-start"),
-    });
+    const operation = argv[1];
+    if (operation === "status" || operation === "restart") {
+      const { runMcpControlCli } = require("../src/runtime/daemon/mcpControl");
+      await runMcpControlCli(operation, { json: argv.includes("--json") });
+    } else if (operation === "configure") {
+      const { runMcpConfigureCli } = require("../src/runtime/daemon/mcpConfigure");
+      runMcpConfigureCli(argv[2], { dryRun: argv.includes("--dry-run") });
+    } else {
+      await runMcpServer({
+        autoStart: !argv.includes("--no-auto-start"),
+      });
+    }
     return;
   }
   if (cmd === "agent-runner") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "3.0.18",
+  "version": "3.0.20",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",
@@ -56,6 +56,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.138",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@openai/codex-sdk": "^0.145.0",
     "@xterm/addon-serialize": "^0.14.0",
     "@xterm/headless": "^6.0.0",

package/src/app/chat/commandExecutor.js

@@ -357,10 +357,12 @@ function createCommandExecutor(options = {}) {
   }
 
   function logMcpHelp() {
-    logMessage("system", "{cyan-fg}MCP bridge:{/cyan-fg} local stdio bridge for external MCP-capable agents");
-    logMessage("system", "  • Configure client command: ufoo mcp");
+    logMessage("system", "{cyan-fg}MCP server:{/cyan-fg} singleton listener in the global controller daemon");
+    logMessage("system", "  • Configure Codex direct HTTP: ufoo mcp configure codex");
+    logMessage("system", "  • Compatibility proxy command: ufoo mcp");
     logMessage("system", "  • Disable daemon auto-start: ufoo mcp --no-auto-start");
-    logMessage("system", "  • Topology: one global bridge, project tools route through registered project daemons");
+    logMessage("system", "  • Listener control: ufoo mcp status | ufoo mcp restart");
+    logMessage("system", "  • Topology: one global tool router; project calls use registered project runtimes");
     logMessage("system", "  • Chat diagnostics: /mcp status, /mcp tools, /mcp help");
   }
 
@@ -417,8 +419,12 @@ function createCommandExecutor(options = {}) {
           throw new Error("empty MCP status response");
         }
         const projects = Array.isArray(status.projects) ? status.projects : [];
-        logMessage("system", "{cyan-fg}MCP bridge:{/cyan-fg} local stdio server");
-        logMessage("system", "  • command: {cyan-fg}ufoo mcp{/cyan-fg}");
+        logMessage("system", "{cyan-fg}MCP server:{/cyan-fg} global Streamable HTTP listener");
+        logMessage("system", `  • listener: ${status.http?.running ? "{green-fg}running{/green-fg}" : "{yellow-fg}not running{/yellow-fg}"}`);
+        if (status.http?.endpoint) {
+          logMessage("system", `  • endpoint: ${escapeBlessed(status.http.endpoint)}`);
+        }
+        logMessage("system", "  • stdio fallback: {cyan-fg}ufoo mcp{/cyan-fg}");
         logMessage("system", `  • global controller: ${escapeBlessed(status.global_controller_root || "")}`);
         logMessage("system", `  • daemon: ${status.global_controller_running ? "{green-fg}running{/green-fg}" : "{yellow-fg}not running{/yellow-fg}"}`);
         logMessage("system", "  • client auto-start: enabled by default");

package/src/app/cli/run.js

@@ -587,7 +587,7 @@ async function runCli(argv) {
       });
     program
       .command("mcp")
-      .description("Run the local global ufoo MCP bridge over stdio")
+      .description("Run the global MCP stdio proxy; use bin entry for listener status/configuration")
       .option("--no-auto-start", "Do not auto-start the home-scoped global controller daemon")
       .action((opts) => {
         const repoRoot = getPackageRoot();
@@ -1809,8 +1809,7 @@ async function runCli(argv) {
     return;
   }
   if (cmd === "mcp") {
-    const mcpArgs = ["mcp"];
-    if (rest.includes("--no-auto-start")) mcpArgs.push("--no-auto-start");
+    const mcpArgs = ["mcp", ...rest];
     run(resolveNodeExecutable(), [path.join(repoRoot, "bin", "ufoo.js"), ...mcpArgs]);
     return;
   }

package/src/config.js

@@ -36,6 +36,7 @@ const DEFAULT_CONFIG = {
   launchMode: "auto",
   agentProvider: "codex-cli",
   controllerMode: "main",
+  mcpPort: 47631,
   codexInternalThreadMode: "api",
   codexAuthPath: "",
   codexOauthRefreshWindowSec: 300,
@@ -125,6 +126,12 @@ function normalizeCodexInternalThreadMode(value) {
   return "legacy";
 }
 
+function normalizeMcpPort(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) return DEFAULT_CONFIG.mcpPort;
+  return parsed;
+}
+
 function normalizeCodexAuthPath(value) {
   return typeof value === "string" ? value.trim() : "";
 }
@@ -184,6 +191,7 @@ function loadConfig(projectRoot) {
       controllerMode: Object.prototype.hasOwnProperty.call(raw, "controllerMode")
         ? normalizeControllerMode(raw.controllerMode)
         : DEFAULT_CONFIG.controllerMode,
+      mcpPort: normalizeMcpPort(raw.mcpPort),
       codexInternalThreadMode: Object.prototype.hasOwnProperty.call(raw, "codexInternalThreadMode")
         ? normalizeCodexInternalThreadMode(raw.codexInternalThreadMode)
         : DEFAULT_CONFIG.codexInternalThreadMode,
@@ -240,6 +248,7 @@ function saveConfig(projectRoot, config) {
   merged.routerProvider = typeof merged.routerProvider === "string" ? merged.routerProvider.trim() : "";
   merged.routerModel = typeof merged.routerModel === "string" ? merged.routerModel.trim() : "";
   merged.controllerMode = normalizeControllerMode(merged.controllerMode);
+  merged.mcpPort = normalizeMcpPort(merged.mcpPort);
   merged.codexInternalThreadMode = normalizeCodexInternalThreadMode(merged.codexInternalThreadMode);
   merged.codexAuthPath = normalizeCodexAuthPath(merged.codexAuthPath);
   merged.codexOauthRefreshWindowSec = normalizeCodexOauthRefreshWindowSec(merged.codexOauthRefreshWindowSec);
@@ -291,6 +300,7 @@ module.exports = {
   defaultRouterProviderForAgentProvider,
   defaultRouterModelForProvider,
   normalizeControllerMode,
+  normalizeMcpPort,
   normalizeCodexInternalThreadMode,
   normalizeCodexAuthPath,
   normalizeCodexOauthRefreshWindowSec,

package/src/coordination/bus/subscriber.js

@@ -100,6 +100,15 @@ function hasProviderSession(meta) {
   return typeof meta?.provider_session_id === "string" && meta.provider_session_id.trim() !== "";
 }
 
+function isManagedMcpRegistration(meta) {
+  return Boolean(meta && meta.mcp_bridge === true && meta.mcp_agent_handle_hash);
+}
+
+function isRecentMcpHeartbeat(meta, nowMs = Date.now()) {
+  const lastSeenMs = Date.parse(String(meta?.last_seen || ""));
+  return Number.isFinite(lastSeenMs) && nowMs - lastSeenMs <= 30 * 1000;
+}
+
 /**
  * 订阅者管理
  */
@@ -458,6 +467,29 @@ class SubscriberManager {
     if (!this.busData.agents) return;
 
     for (const [id, meta] of Object.entries(this.busData.agents)) {
+      if (isManagedMcpRegistration(meta)) {
+        const expiresAtMs = Date.parse(String(meta.mcp_lease_expires_at || ""));
+        const expired = !Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now();
+        if (!expired || isRecentMcpHeartbeat(meta)) {
+          continue;
+        }
+        if (meta.status === "active") {
+          this.logRegistry("cleanup_inactive_mark", {
+            source: "bus.subscriber.cleanupInactive",
+            subscriber: id,
+            reason: "mcp_agent_lease_expired",
+            status: meta.status || "",
+            launch_mode: meta.launch_mode || "",
+            last_seen: meta.last_seen || "",
+            lease_expires_at: meta.mcp_lease_expires_at || "",
+          });
+          meta.status = "inactive";
+          meta.activity_state = "";
+          meta.mcp_revoked_at = getTimestamp();
+          this.cleanupSubscriberArtifacts(id);
+        }
+        continue;
+      }
       if (isInternalLaunchMode(meta)) {
         const recoverable = hasProviderSession(meta);
         if (meta.status === "inactive") {

package/src/coordination/state/paths.js

@@ -24,6 +24,8 @@ function getUfooPaths(projectRoot) {
   const ufooDaemonPid = path.join(runDir, "ufoo-daemon.pid");
   const ufooDaemonLog = path.join(runDir, "ufoo-daemon.log");
   const ufooSock = path.join(runDir, "ufoo.sock");
+  const mcpToken = path.join(runDir, "mcp-token");
+  const mcpEndpoint = path.join(runDir, "mcp-endpoint.json");
 
   return {
     ufooDir,
@@ -46,6 +48,8 @@ function getUfooPaths(projectRoot) {
     ufooDaemonPid,
     ufooDaemonLog,
     ufooSock,
+    mcpToken,
+    mcpEndpoint,
   };
 }
 

package/src/runtime/contracts/eventContract.js

@@ -20,6 +20,10 @@ const IPC_REQUEST_TYPES = {
   AGENT_REPORT: "agent_report",
   ASSIGN_ROLE: "assign_role",
   REFRESH_STATUS: "refresh_status",
+  CONTROL_PLANE_CALL: "control_plane_call",
+  CONTROL_PLANE_CANCEL: "control_plane_cancel",
+  MCP_STATUS: "mcp_status",
+  MCP_RESTART: "mcp_restart",
 };
 
 const IPC_RESPONSE_TYPES = {
@@ -29,6 +33,7 @@ const IPC_RESPONSE_TYPES = {
   ERROR: "error",
   BUS_SEND_OK: "bus_send_ok",
   REGISTER_OK: "register_ok",
+  CONTROL_PLANE_RESULT: "control_plane_result",
 };
 
 const BUS_STATUS_PHASES = {