u-foo 3.0.17 → 3.0.18

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

@@ -26,13 +26,14 @@ 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`.
+   call bare `ufoo bus join` or borrow another subscriber. Keep the returned
+   value as the external Agent's identity.
 3. Select the receive mechanism from the host App's actual wake capability,
    never from Agent type:
 
@@ -44,8 +45,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
 
@@ -80,14 +82,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:

package/README.md

@@ -130,8 +130,8 @@ ufoo mcp
 
 ### 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
@@ -145,9 +145,11 @@ ufoo supports two Agent delivery modes, selected only by the presence of
   `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,8 +237,7 @@ 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.
 
 - **Codex App:** call MCP `wait_for_message` in the foreground with
   `after_seq: 0` and `timeout_seconds: 600`. The tool call stays pending inside
@@ -244,8 +245,9 @@ do not export it as `UFOO_SUBSCRIBER_ID`.
   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
+- **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 +256,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

@@ -127,7 +127,8 @@ ufoo mcp
 
 ### Agent 消息投递模式
 
-ufoo 支持两种 Agent 投递模式，只根据 `UFOO_SUBSCRIBER_ID` 是否存在来选择：
+ufoo 支持两种 Agent 投递模式，只根据启动辅助 terminal 之前，宿主 Agent
+继承的 `UFOO_SUBSCRIBER_ID` 是否存在来选择：
 
 - 包装器托管的 Agent 通过 `ucodex`、`uclaude`、`uagy`、`ukimi` 或 `ucode`
   启动。包装器会提供 `UFOO_SUBSCRIBER_ID`；ufoo 能监控其 shell 活动并定位
@@ -138,9 +139,10 @@ ufoo 支持两种 Agent 投递模式，只根据 `UFOO_SUBSCRIBER_ID` 是否存
   无 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 +225,26 @@ ufoo skills list --optional
 ufoo skills install ufoo-bus-poll --target /path/to/that/agent/skills
 ```
 
-先通过 MCP `register_agent` 注册一次并保留返回的 subscriber，不要将它
-导出成 `UFOO_SUBSCRIBER_ID`。
+先通过 MCP `register_agent` 注册一次并保留返回的 subscriber。
 
 - **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`，设置
+- **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
@@ -24,9 +25,12 @@ capabilities from the Agent type or subscriber prefix.
 - 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.
+  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
+  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

package/SKILLS/ufoo-bus/SKILL.md

@@ -21,7 +21,8 @@ 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
@@ -29,9 +30,12 @@ Use `UFOO_SUBSCRIBER_ID` as the only delivery-mode signal:
   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.
+  returned value as `<subscriber-id>` for later MCP and CLI operations. 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`.
@@ -101,11 +105,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

package/package.json

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

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:

package/src/code/UCODE_PROMPT.md

@@ -17,7 +17,7 @@ ufoo integration requirements:
 - 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: