u-foo 3.0.17 → 3.0.19

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

@@ -26,13 +26,16 @@ the host's maximum pending-call window ends.
 
 ## Attach the subscriber
 
-1. Inspect `UFOO_SUBSCRIBER_ID`. If it is nonempty, stop this workflow: the
+1. Inspect the host Agent's inherited `UFOO_SUBSCRIBER_ID` before starting or
+   mutating any helper terminal. If it is nonempty, stop this workflow: the
    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`, borrow another subscriber, or export the MCP
-   result as `UFOO_SUBSCRIBER_ID`.
+   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:
 
@@ -44,8 +47,9 @@ the host's maximum pending-call window ends.
 
 Agent type and subscriber prefix are not capability signals. An externally
 hosted MCP subscriber named `codex:*`, `claude-code:*`, or any other type is
-eligible because the absent environment variable—not its name—selected this
-delivery mode.
+eligible because the Agent's inherited environment—not its name—selected this
+delivery mode. A variable exported later inside a dedicated helper terminal
+does not reclassify the host Agent as wrapper-managed.
 
 ## Use Codex App pending MCP wait
 
@@ -57,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
@@ -64,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.
@@ -80,14 +85,21 @@ Never run two pending waits for the same subscriber.
 1. Check for an existing `ufoo bus poll ... --follow` process for the literal
    MCP subscriber. Keep one healthy process; the CLI rejects a duplicate
    receive lease.
-2. Start this command through Cursor's monitored background shell:
+2. Start this command through Cursor's monitored background shell. Bind the
+   MCP-returned subscriber inside that dedicated terminal, then launch the
+   resident poll:
 
    ```bash
-   ufoo bus poll "<mcp-subscriber-id>" --follow --interval 30
+   export UFOO_SUBSCRIBER_ID="<mcp-subscriber-id>"
+   exec ufoo bus poll "$UFOO_SUBSCRIBER_ID" --follow --interval 30
    ```
 
    Use `30` seconds by default; accept `15`–`120` when the user requests a
    different latency. Do not use `nohup`, shell `&`, or an OS-detached daemon.
+   This terminal-local export gives its CLI commands a stable sender/subscriber
+   identity. It must happen only after the host Agent was classified as
+   external and registered through MCP; it is not evidence of wrapper launch
+   or direct-injection support.
 3. Start the monitored task with
    `block_until_ms: 0`.
 4. Configure `notify_on_output` with:
@@ -118,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
@@ -127,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,16 +134,19 @@ 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
 
-ufoo supports two Agent delivery modes, selected only by the presence of
-`UFOO_SUBSCRIBER_ID`:
+ufoo supports two Agent delivery modes, selected only from the host Agent's
+inherited `UFOO_SUBSCRIBER_ID` before any helper terminal is started:
 
 - Wrapper-managed Agents start through `ucodex`, `uclaude`, `uagy`, `ukimi`, or
   `ucode`. The wrapper provides `UFOO_SUBSCRIBER_ID`; ufoo monitors the shell
@@ -140,14 +155,17 @@ ufoo supports two Agent delivery modes, selected only by the presence of
   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`.
 
 Agent type names and subscriber prefixes are routing metadata, not capability
-signals. External Agents must not export the MCP subscriber as
-`UFOO_SUBSCRIBER_ID`, because that variable specifically marks the
-wrapper-managed path.
+signals. After an external Cursor Agent registers through MCP, its dedicated
+listener terminal may export the returned subscriber as
+`UFOO_SUBSCRIBER_ID` so CLI operations share one identity. That child-shell
+binding does not alter the host Agent's already selected external mode and is
+not evidence of wrapper injection.
 
 Chat is a UI client. The daemon owns project runtime state. Agents communicate
 through bus queues, prompt injection, shared memory, reports, and tool handlers
@@ -235,17 +253,21 @@ ufoo skills list --optional
 ufoo skills install ufoo-bus-poll --target /path/to/that/agent/skills
 ```
 
-Register once through MCP `register_agent`, retain its returned subscriber, and
-do not export it as `UFOO_SUBSCRIBER_ID`.
+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.
-- **Cursor:** run
-  `ufoo bus poll "<subscriber-id>" --follow --interval 30` through the monitored
+  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
   background shell with `block_until_ms: 0`, and configure
   `notify_on_output` to match `\[ufoo\]`. Startup and empty intervals are
   silent; only ufoo-delivered messages wake the model.
@@ -254,10 +276,12 @@ Both paths keep idle queue checks outside the LLM. A background PTY alone is
 not a wake mechanism in Codex App.
 
 The poll skill is not installed by postinstall or `skills install all`.
-Wrapper-managed Agents skip MCP registration and external waiting whenever
-`UFOO_SUBSCRIBER_ID` is present. Receive-path selection depends on host App
-capabilities, never on whether the external Agent calls itself Codex, Claude,
-Cursor, or another type.
+Wrapper-managed Agents skip MCP registration and external waiting when
+`UFOO_SUBSCRIBER_ID` was present in the Agent's inherited launch environment.
+A value exported later inside a Cursor listener terminal does not rerun this
+classification. Receive-path selection depends on host App capabilities, never
+on whether the external Agent calls itself Codex, Claude, Cursor, or another
+type.
 
 ### Context, Memory, History, Reports
 

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,28 +123,34 @@ 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 消息投递模式
 
-ufoo 支持两种 Agent 投递模式，只根据 `UFOO_SUBSCRIBER_ID` 是否存在来选择：
+ufoo 支持两种 Agent 投递模式，只根据启动辅助 terminal 之前，宿主 Agent
+继承的 `UFOO_SUBSCRIBER_ID` 是否存在来选择：
 
 - 包装器托管的 Agent 通过 `ucodex`、`uclaude`、`uagy`、`ukimi` 或 `ucode`
   启动。包装器会提供 `UFOO_SUBSCRIBER_ID`；ufoo 能监控其 shell 活动并定位
   注入端点，因此可以直接注入 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 前缀只是路由元数据，不是能力判断条件。外部 Agent
-不要把 MCP 返回的 subscriber 导出成 `UFOO_SUBSCRIBER_ID`，因为该变量专门
-表示包装器托管链路。
+Agent 类型名和 subscriber 前缀只是路由元数据，不是能力判断条件。外部
+Cursor Agent 通过 MCP 注册后，可以在专用监听 terminal 内把返回的
+subscriber 导出为 `UFOO_SUBSCRIBER_ID`，让 CLI 操作复用同一身份。这个
+子 shell 绑定不会改变宿主 Agent 已选择的外部模式，也不代表支持包装器注入。
 
 Chat 是 UI client。daemon 拥有项目运行态。Agent 通过 bus queue、prompt
 injection、shared memory、report 和 tool handler 协作，而不是直接依赖
@@ -223,25 +233,29 @@ ufoo skills list --optional
 ufoo skills install ufoo-bus-poll --target /path/to/that/agent/skills
 ```
 
-先通过 MCP `register_agent` 注册一次并保留返回的 subscriber，不要将它
-导出成 `UFOO_SUBSCRIBER_ID`。
-
-- **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` 续挂。
-- **Cursor：**通过 monitored background shell 运行
-  `ufoo bus poll "<subscriber-id>" --follow --interval 30`，设置
+先通过 MCP `register_agent` 注册一次并保留返回的 subscriber 与
+`agent_handle`。heartbeat、activity、send、receive、ack、report 和
+unregister 都带上该 handle；它是所有权凭证，不应发送给其他 Agent，也不应
+写进 report。
+
+- **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`，设置
   `block_until_ms: 0`，并让 `notify_on_output` 匹配 `\[ufoo\]`。启动和
   空轮询保持静默，只有 ufoo 投递消息会唤醒模型。
 
 两条路径都把空闲检查留在 LLM 之外。仅有后台 PTY 输出并不能唤醒 Codex App。
 
-poll skill 不会由 postinstall 或 `skills install all` 安装。只要环境中存在
-`UFOO_SUBSCRIBER_ID`，包装器托管的 Agent 就跳过 MCP 注册和外部等待。
-接收链路由宿主 App 的能力决定，与外部 Agent 叫 Codex、Claude、Cursor
-或其他类型无关。
+poll skill 不会由 postinstall 或 `skills install all` 安装。如果
+`UFOO_SUBSCRIBER_ID` 在 Agent 启动时的继承环境中已经存在，包装器托管的
+Agent 就跳过 MCP 注册和外部等待；之后在 Cursor 监听 terminal 中导出的值
+不会重新触发这次分类。接收链路由宿主 App 的能力决定，与外部 Agent 叫
+Codex、Claude、Cursor 或其他类型无关。
 
 ### Context、Memory、History、Report
 

package/SKILLS/ufoo/SKILL.md

@@ -14,7 +14,8 @@ Apply the unified workspace protocol. Use `$ufoo-bus`, `$ufoo-context`, or
 
 ## Resolve the bus delivery mode
 
-Use the shell environment as the only delivery-mode signal. Do not infer
+Use the host Agent's inherited launch environment as the only delivery-mode
+signal. Evaluate it before creating or mutating helper terminals. Do not infer
 capabilities from the Agent type or subscriber prefix.
 
 - If `UFOO_SUBSCRIBER_ID` is nonempty, the Agent was started by a ufoo wrapper
@@ -22,15 +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, do not export it as `UFOO_SUBSCRIBER_ID`, and invoke
-  `$ufoo-bus-poll` to establish the receive path using this host App's own
-  no-token wait and self-wake primitive.
+  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
 
@@ -56,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

@@ -21,17 +21,24 @@ Verify `.ufoo/bus/` exists. If it does not, initialize it:
 ufoo init --targets bus --project "$(pwd)"
 ```
 
-Use `UFOO_SUBSCRIBER_ID` as the only delivery-mode signal:
+Use the host Agent's inherited `UFOO_SUBSCRIBER_ID` as the only delivery-mode
+signal. Evaluate it before creating or mutating helper terminals:
 
 - Nonempty: this is a wrapper-managed Agent. The wrapper already registered
   the subscriber and the daemon can inject into its monitored shell. Reuse the
   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; do not
-  export it as `UFOO_SUBSCRIBER_ID`. Invoke `$ufoo-bus-poll` once at session
-  start to select the receive path supported by the host App.
+  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
+  registration. Never use that helper-local value to reclassify the host as
+  wrapper-managed.
 
 Never choose a delivery mode from an Agent type such as `codex`, `cursor`, or
 `claude-code`. Agents do not self-register with bare `ufoo bus join`.
@@ -45,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.
 
@@ -64,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.
 
@@ -88,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 `*`.
 
@@ -101,11 +110,12 @@ keep their App-specific receive wait armed when idle.
 
 ## Delegate resident watching
 
-For an externally hosted Agent with no `UFOO_SUBSCRIBER_ID`, invoke
-`$ufoo-bus-poll` at session start and follow it end-to-end. This is its normal
-receive path, not an Agent-type fallback. That skill selects pending MCP
-`wait_for_message` for Codex App or monitored background stdout for Cursor.
-Never invoke it when the environment variable is present.
+For an externally hosted Agent whose inherited launch environment had no
+`UFOO_SUBSCRIBER_ID`, invoke `$ufoo-bus-poll` at session start and follow it
+end-to-end. This is its normal receive path, not an Agent-type fallback. That
+skill selects pending MCP `wait_for_message` for Codex App or monitored
+background stdout for Cursor. Never invoke it when the variable was already
+present before helper-terminal setup.
 
 Do not implement a timer, tick, sleep/check loop, or second resident mechanism
 in this skill. Do not arm resident watching merely because a message was sent
@@ -115,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>"
@@ -125,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 Codex HTTP configuration 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.17",
+  "version": "3.0.19",
   "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/agents/prompts/groupBootstrap.js

@@ -38,7 +38,7 @@ const SHARED_UFOO_PROTOCOL = [
   "coordination — never for greetings, acknowledgments, or emoji alone.",
   "Those create reply loops between agents.",
   "",
-  "A nonempty `UFOO_SUBSCRIBER_ID` means the ufoo wrapper/daemon already",
+  "A nonempty `UFOO_SUBSCRIBER_ID` in this Agent's inherited launch environment means the ufoo wrapper/daemon already",
   "registered this Agent and can inject into its monitored session. Reuse that",
   "identity; never call MCP `register_agent`, run bare `ufoo bus join`, or",
   "start resident `ufoo bus poll`.",

package/src/agents/prompts/native/ufoo.js

@@ -9,7 +9,7 @@ Participate in multi-agent coordination through the ufoo bus/context system:
 - Use shared memory for durable project facts. Read existing memory before writing new memory; do not use it for transient task state.
 - Support launch/close/resume/inject flows managed by ufoo daemon.
 - Prefer canonical ufoo commands (\`ufoo ctx\`, \`ufoo bus\`, \`ufoo memory\`, \`ufoo report\`) for coordination and status sync.
-- A nonempty \`UFOO_SUBSCRIBER_ID\` means the ufoo wrapper/daemon already registered this Agent and can inject directly into its monitored session. Reuse that identity; never call MCP \`register_agent\`, run bare \`ufoo bus join\`, or start resident \`ufoo bus poll\`.
+- A nonempty \`UFOO_SUBSCRIBER_ID\` in this Agent's inherited launch environment means the ufoo wrapper/daemon already registered this Agent and can inject directly into its monitored session. Reuse that identity; never call MCP \`register_agent\`, run bare \`ufoo bus join\`, or start resident \`ufoo bus poll\`.
 - After sending a bus message, do not poll \`ufoo bus check\`, invoke \`/ubus\`, sleep, or wait for a reply. Continue the current task; any follow-up message will be automatically injected into your prompt/session.
 
 Execution protocol: