u-foo 3.0.16 → 3.0.17

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

@@ -1,60 +1,144 @@
 ---
 name: ufoo-bus-poll
 description: >-
-  Stream pending ufoo bus messages through a resident background task for an
-  MCP-registered or externally provisioned agent whose host cannot receive
-  automatic ufoo prompt injection. Use only with a host that forwards streaming
-  background-task output into the agent session; do not use for Codex CLI,
-  Claude Code CLI, Agy, Kimi, or native ucode.
+  Establish no-token idle bus monitoring and self-wake for an externally
+  hosted, MCP-registered Agent with no wrapper-provided UFOO_SUBSCRIBER_ID.
+  Select the host App's native wake mechanism: pending MCP wait_for_message for
+  Codex App or monitored background stdout for Cursor. Do not use for
+  wrapper-managed Agents.
 ---
 
 # ufoo bus poll
 
-Attach one provisioned external subscriber to a host-managed background stream.
-Keep the stream queue-read-only so the agent controls acknowledgement.
+Attach one subscriber to the host App's own wait primitive. Keep queue reads
+non-mutating so the Agent acknowledges only after handling work.
 
-## Attach the registered subscriber
+This is the standard receive channel for an external MCP Agent. It is not an
+ad-hoc reply wait and is not selected by Agent type. The runtime permits only
+one active receive wait per subscriber.
 
-1. Reuse the exact subscriber returned by MCP `register_agent` or supplied by
-   the host. Never create a second identity for the stream, call bare
-   `ufoo bus join`, guess an agent type, or borrow another workspace subscriber.
-2. Start exactly one streaming background task for that subscriber:
+## Preserve the token boundary
+
+Keep idle checks inside a pending tool call or host background task. Do not
+implement a model-driven timer, repeated chat turn, or fixed
+`AGENT_LOOP_TICK_*`. Waiting must not invoke the LLM until a message arrives or
+the host's maximum pending-call window ends.
+
+## Attach the subscriber
+
+1. Inspect `UFOO_SUBSCRIBER_ID`. 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`.
+3. Select the receive mechanism from the host App's actual wake capability,
+   never from Agent type:
+
+   - Codex App: use the pending MCP workflow below.
+   - Cursor with `notify_on_output`: use the monitored stdout workflow below.
+   - Another App: use its documented pending-tool or output-notification
+     primitive. If neither exists, automatic self-wake is unavailable; use an
+     explicit `$ufoo-bus` check or a user-approved scheduled fallback.
+
+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.
+
+## Use Codex App pending MCP wait
+
+Codex App does not resume the current task when a background shell or PTY later
+prints stdout. Keep the wait inside one foreground MCP tool call instead:
+
+1. When active work is complete and the inbox should remain armed, call MCP
+   `wait_for_message` with:
+
+   - `project_root`: the registered project root
+   - `subscriber`: the caller-owned MCP subscriber
+   - `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
+   `ufoo bus poll --follow`; while the tool is pending, internal queue checks do
+   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.
+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.
+5. After handling a message batch and completing any active work, re-arm one
+   wait with the returned `last_seq`. Advance the cursor only after `ack_bus`
+   succeeds; if acknowledgement fails, resolve that failure before re-arming.
+   On cancellation or an explicit stop, leave it disarmed.
+
+Never run two pending waits for the same subscriber.
+
+## Configure Cursor wake-on-output
+
+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:
 
    ```bash
-   ufoo bus poll "<subscriber-id>" --follow --interval 2
+   ufoo bus poll "<mcp-subscriber-id>" --follow --interval 30
    ```
 
-3. Keep the command owned by the host's streaming background-task facility.
-   Do not use `nohup`, shell `&`, or an OS-detached daemon; those routes can
-   write output somewhere the agent never receives.
+   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.
+3. Start the monitored task with
+   `block_until_ms: 0`.
+4. Configure `notify_on_output` with:
+
+   - pattern: `\[ufoo\]`
+   - reason: `ufoo bus pending`
+5. Inspect the terminal once to confirm the process started. Idle success is
+   a running task with no output; do not wait for a heartbeat.
+6. If pending output appears during startup, handle it as the first stream
+   batch. Do not run a parallel foreground `ufoo bus check`.
+
+Empty intervals emit nothing, so they neither wake Cursor nor consume model
+tokens. Match the general `[ufoo]` protocol prefix rather than a specific
+`<from:...>` shape so every message delivered by ufoo can wake the session.
+Startup and lifecycle checks also emit nothing; process health comes from the
+host task state and the single-subscriber lease.
+
+This process wakes only its own Cursor session. A peer that must react while
+unattended needs its own armed poll or another real wake channel.
 
-The command rejects a second resident poll for the same subscriber. It emits
-the current pending batch, waits for that batch to be acknowledged, then emits
-the next batch. It never acknowledges, claims, injects, or clears messages.
+## Handle delivered batches
 
-## Handle stream batches
+For Codex App, read the structured `messages` returned by `wait_for_message`.
+For Cursor, handle every `[ufoo]<from:...>` event in the emitted batch.
 
-For every `[ufoo]<from:...>` event:
+1. Read each event's `data.message` or printed `Content.message`, then execute
+   actionable work.
+2. Acknowledge only after handling:
 
-1. Read `Content.message` and execute actionable work.
-2. After handling the emitted batch, run the exact acknowledgement command
-   printed by the stream:
+   - Codex App: MCP `ack_bus` with the returned `last_seq` as `through_seq`.
+   - Cursor: run the exact command printed by the stream:
 
    ```bash
    ufoo bus ack "<subscriber-id>" --through <seq>
    ```
 
-   Preserve `--through`; it keeps later messages pending.
+   Preserve the sequence boundary so later messages stay pending.
 3. Reply only with a requested result, answer, blocker, or fact the sender
-   needs:
-
-   ```bash
-   ufoo bus send "<sender-id>" "<substantive result>"
-   ```
+   needs. Use MCP `dispatch_message` with the same `project_root`,
+   caller-owned subscriber, 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; do not start another poll, sleep, or wait.
-The resident stream delivers follow-up output.
+sending, continue the current task. Keep the existing Cursor stream running, or
+re-arm one Codex App wait only after active work is complete.
+
+## Stop resident watching
+
+When the user asks to stop:
 
-If the host cannot forward incremental output from a still-running task, stop
-this workflow and use an explicitly invoked `$ufoo-bus` inbox check instead.
+1. Codex App: cancel the pending `wait_for_message` call and do not re-arm it.
+2. Cursor: stop the tracked poll process or matching terminal task and consume
+   its shell-completion notification.
+3. Confirm that the App-specific receive wait stopped.

package/OPTIONAL_SKILLS/ufoo-bus-poll/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "ufoo bus poll"
-  short_description: "Stream ufoo bus messages for non-injectable agents"
-  default_prompt: "Use $ufoo-bus-poll to attach this MCP-registered agent to its resident ufoo bus stream."
+  short_description: "Wake external Agents with App-native idle waits"
+  default_prompt: "Use $ufoo-bus-poll to arm this external Agent with Codex App's pending MCP wait or Cursor's monitored stdout wake path."

package/README.md

@@ -27,7 +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 for external MCP-capable agents.
+- `ufoo mcp`, a local global MCP bridge with pending-call bus wake for external
+  MCP-capable agents.
 
 ## Requirements
 
@@ -127,6 +128,27 @@ ufoo mcp
   -> selected project daemon for bus/report/activity state
 ```
 
+### Agent Delivery Modes
+
+ufoo supports two Agent delivery modes, selected only by the presence of
+`UFOO_SUBSCRIBER_ID`:
+
+- Wrapper-managed Agents start through `ucodex`, `uclaude`, `uagy`, `ukimi`, or
+  `ucode`. The wrapper provides `UFOO_SUBSCRIBER_ID`; ufoo monitors the shell
+  activity and injection endpoint, so bus messages can be injected directly.
+  These Agents reuse the environment identity and do not register through MCP
+  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:
+  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.
+
 Chat is a UI client. The daemon owns project runtime state. Agents communicate
 through bus queues, prompt injection, shared memory, reports, and tool handlers
 instead of importing chat UI code.
@@ -204,23 +226,38 @@ Use `/bus status` to find the real subscriber ID or resolvable nickname
 before sending. Agents should handle pending work, reply to the sender, and
 acknowledge their queue.
 
-Agent hosts that cannot receive ufoo prompt injection can opt into a resident,
-queue-read-only bus stream:
+Externally hosted Agents with no `UFOO_SUBSCRIBER_ID` use the opt-in
+`ufoo-bus-poll` skill to select their host App's queue-read-only wait and
+self-wake mechanism:
 
 ```bash
 ufoo skills list --optional
 ufoo skills install ufoo-bus-poll --target /path/to/that/agent/skills
-ufoo bus poll "<subscriber-id>" --follow --interval 2
 ```
 
-Use the subscriber returned by MCP `register_agent` or provisioned by the host,
-then run the final command through that host's streaming background-task facility.
-It prints newly observed pending events but never claims or acknowledges them;
-the agent runs the printed `ufoo bus ack --through <seq>` command only after
-handling the emitted batch, preserving later arrivals. The fallback is not
-installed by postinstall or `skills install all`, and follow mode refuses Codex
-CLI, Claude Code CLI, Agy, Kimi, and native ucode subscriber types so their
-existing delivery paths remain untouched.
+Register once through MCP `register_agent`, retain its returned subscriber, and
+do not export it as `UFOO_SUBSCRIBER_ID`.
+
+- **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
+  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.
+
+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.
 
 ### Context, Memory, History, Reports
 

package/README.zh-CN.md

@@ -25,7 +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，供支持 MCP 的外部 Agent 接入。
+- 提供 `ufoo mcp` 本机 global MCP bridge，并用 pending tool call 唤醒支持
+  MCP 的外部 Agent。
 
 ## 环境要求
 
@@ -124,6 +125,23 @@ ufoo mcp
   -> selected project daemon for bus/report/activity state
 ```
 
+### Agent 消息投递模式
+
+ufoo 支持两种 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` 的后台输出。
+
+Agent 类型名和 subscriber 前缀只是路由元数据，不是能力判断条件。外部 Agent
+不要把 MCP 返回的 subscriber 导出成 `UFOO_SUBSCRIBER_ID`，因为该变量专门
+表示包装器托管链路。
+
 Chat 是 UI client。daemon 拥有项目运行态。Agent 通过 bus queue、prompt
 injection、shared memory、report 和 tool handler 协作，而不是直接依赖
 chat UI 代码。
@@ -197,22 +215,33 @@ ufoo -g
 发送消息前，先用 `/bus status` 查看真实 subscriber ID 或可解析昵称。
 Agent 应处理 pending work、回复发送方，并 ack 自己的队列。
 
-无法接收 ufoo prompt 注入的 Agent host 可以显式启用常驻、队列只读的
-bus 消息流：
+没有 `UFOO_SUBSCRIBER_ID` 的外部 Agent 使用可选的 `ufoo-bus-poll` skill，
+由它选择宿主 App 对应的队列只读等待和自身唤醒方式：
 
 ```bash
 ufoo skills list --optional
 ufoo skills install ufoo-bus-poll --target /path/to/that/agent/skills
-ufoo bus poll "<subscriber-id>" --follow --interval 2
 ```
 
-使用 MCP `register_agent` 返回或由 host 预配的 subscriber，并由该 host 的
-流式后台任务能力托管最后一条命令。它只输出新观察到的
-pending event，不 claim、不 ack；Agent 处理完输出批次后，再执行输出中
-给出的 `ufoo bus ack --through <seq>`，以保留稍后到达的消息。
-这个 fallback 不会被 postinstall 或 `skills install all` 安装，而且
-follow 模式会拒绝 Codex CLI、Claude Code CLI、Agy、Kimi 和原生 ucode
-的 subscriber 类型，确保其现有投递链路不受影响。
+先通过 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`，设置
+  `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
+或其他类型无关。
 
 ### Context、Memory、History、Report
 

package/SKILLS/ufoo/SKILL.md

@@ -12,6 +12,26 @@ description: >-
 Apply the unified workspace protocol. Use `$ufoo-bus`, `$ufoo-context`, or
 `$ufoo-online` when the task needs the focused workflow.
 
+## Resolve the bus delivery mode
+
+Use the shell environment as the only delivery-mode signal. 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
+  and is already registered. Reuse that identity. Do not call MCP
+  `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.
+
+In the sections below, `<subscriber-id>` means the wrapper-provided
+`UFOO_SUBSCRIBER_ID` or the subscriber returned by MCP, according to this
+branch.
+
 ## Synchronize workspace state
 
 1. Read open decisions before related work:
@@ -25,11 +45,12 @@ Apply the unified workspace protocol. Use `$ufoo-bus`, `$ufoo-context`, or
 3. Consume relevant shared memory before writing new memory.
 4. Keep the default as no new decision and no new memory entry.
 
-## Handle injected messages
+## Handle delivered messages
 
 Treat these prompt prefixes as work inputs:
 
-- `[ufoo]<from:id(nickname)>` — event-bus delivery from another agent.
+- `[ufoo]<from:id(nickname)>` — event-bus delivery from direct injection or the
+  resident external-Agent stream.
 - `[manual]<to:id(nickname)>` — manual work directed to this agent.
 
 For each received bus task:
@@ -38,7 +59,7 @@ For each received bus task:
 2. Acknowledge it only after handling:
 
    ```bash
-   ufoo bus ack "$UFOO_SUBSCRIBER_ID"
+   ufoo bus ack "<subscriber-id>"
    ```
 
 3. Reply only with a requested answer, delegated result, or fact the sender
@@ -46,12 +67,13 @@ For each received bus task:
 4. Emit a concise runtime report for delegated work:
 
    ```bash
-   ufoo report done "<summary>" --agent "$UFOO_SUBSCRIBER_ID"
+   ufoo report done "<summary>" --agent "<subscriber-id>"
    ```
 
-After sending or broadcasting a message, continue the current task. Do not
-poll, invoke a bus-check skill, sleep, or wait for a reply; follow-up messages
-are injected automatically.
+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
+App-specific `$ufoo-bus-poll` receive wait armed when idle.
 
 ## Preserve shared knowledge
 
@@ -92,5 +114,5 @@ Initialize only the required targets:
 ufoo init --targets context,bus --project "$(pwd)"
 ```
 
-Reuse an existing subscriber identity after initialization. Join the bus only
-when no current identity can be recovered.
+Initialization does not choose or create an Agent identity. Establish identity
+only through the delivery-mode branch above.

package/SKILLS/ufoo-bus/SKILL.md

@@ -2,9 +2,10 @@
 name: ufoo-bus
 description: >-
   Operate the local ufoo event bus: check and acknowledge pending messages,
-  identify or join a subscriber, inspect status, resolve targets, send results,
-  and broadcast updates. Use when asked to handle bus messages or perform local
-  agent-to-agent routing.
+  establish the correct wrapper or MCP subscriber, inspect status, resolve
+  targets, send results, broadcast updates, and hand external Agents to
+  $ufoo-bus-poll for host App-specific no-token wait and self-wake delivery.
+  Use when asked to handle bus messages or perform local agent-to-agent routing.
 ---
 
 # ufoo bus
@@ -12,7 +13,7 @@ description: >-
 Operate the project-local event bus without creating reply loops or competing
 with automatic prompt injection.
 
-## Establish the subscriber
+## Establish the delivery mode and subscriber
 
 Verify `.ufoo/bus/` exists. If it does not, initialize it:
 
@@ -20,23 +21,34 @@ Verify `.ufoo/bus/` exists. If it does not, initialize it:
 ufoo init --targets bus --project "$(pwd)"
 ```
 
-Prefer `UFOO_SUBSCRIBER_ID`, then recover the current identity:
+Use `UFOO_SUBSCRIBER_ID` as the only delivery-mode signal:
 
-```bash
-ufoo bus whoami
-```
+- 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.
 
-Run `ufoo bus join` only when neither source yields an identity. Rejoining can
-cause identity drift.
+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`.
 
 ## Handle pending messages
 
-Check messages only when this skill was invoked to do so:
+If a wrapper-managed Agent was explicitly asked for a manual inbox check, run:
 
 ```bash
-ufoo bus check "$UFOO_SUBSCRIBER_ID"
+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.
+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.
+
 For every pending batch:
 
 1. Read the sender from `[ufoo]<from:id(nickname)>`.
@@ -44,12 +56,14 @@ For every pending batch:
 3. Acknowledge after handling:
 
    ```bash
-   ufoo bus ack "$UFOO_SUBSCRIBER_ID"
+   ufoo bus ack "<subscriber-id>"
    ```
 
    When a batch supplies a final sequence, prefer
-   `ufoo bus ack "$UFOO_SUBSCRIBER_ID" --through <seq>` so later arrivals stay
-   pending.
+   `ufoo bus ack "<subscriber-id>" --through <seq>` so later arrivals stay
+   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`.
 4. Reply only when the sender requested an answer, delegated work whose result
    is needed, or needs a discovered blocker or fact.
 
@@ -62,31 +76,52 @@ Inspect identities and nicknames before sending:
 
 ```bash
 ufoo bus status
-ufoo bus resolve "$UFOO_SUBSCRIBER_ID" <target>
+ufoo bus resolve "<subscriber-id>" <target>
 ```
 
-Send to an exact subscriber ID, unique nickname, or agent type:
+For a wrapper-managed Agent, send to an exact subscriber ID, unique nickname,
+or Agent type with:
 
 ```bash
 ufoo bus send "<target>" "<substantive message>"
 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.
+
 Target resolution order is exact ID, nickname, agent type, then `*`.
 
 After sending or broadcasting, continue the current task. Do not run
-`ufoo bus check`, poll, sleep, or wait for a reply. Follow-up messages are
-injected into the prompt/session automatically.
+`ufoo bus check`, start another poll, sleep, or wait for a reply.
+Wrapper-managed Agents receive follow-ups by direct injection; external Agents
+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.
+
+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
+and a reply is expected. After an App-specific wake, handle the delivered batch
+using the rules above and leave re-arming or stream lifecycle to
+`$ufoo-bus-poll`.
 
 ## Report delegated work
 
 Use the shared report contract when bus work represents a task:
 
 ```bash
-ufoo report start "<task>" --task <id> --agent "$UFOO_SUBSCRIBER_ID"
-ufoo report progress "<detail>" --task <id> --agent "$UFOO_SUBSCRIBER_ID"
-ufoo report done "<summary>" --task <id> --agent "$UFOO_SUBSCRIBER_ID"
-ufoo report error "<reason>" --task <id> --agent "$UFOO_SUBSCRIBER_ID"
+ufoo report start "<task>" --task <id> --agent "<subscriber-id>"
+ufoo report progress "<detail>" --task <id> --agent "<subscriber-id>"
+ufoo report done "<summary>" --task <id> --agent "<subscriber-id>"
+ufoo report error "<reason>" --task <id> --agent "<subscriber-id>"
 ```
 
 Use `--scope private` only for helper-internal reports.

package/SKILLS/ufoo-bus/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "ufoo bus"
-  short_description: "Handle local ufoo bus messages and agent routing"
-  default_prompt: "Use $ufoo-bus to check and handle pending event-bus work."
+  short_description: "Route wrapper injection and App-native MCP waits"
+  default_prompt: "Use $ufoo-bus to select wrapper injection or the external host App receive path and handle pending bus work."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "3.0.16",
+  "version": "3.0.17",
   "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,6 +38,11 @@ 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",
+  "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`.",
+  "",
   "`ufoo bus send <target> \"<message>\"`",
   "",
   "After sending, do not poll `ufoo bus check`, invoke `/ubus`, sleep, or wait",

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

@@ -9,6 +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\`.
 - 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,6 +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`.
 - 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/coordination/bus/index.js

@@ -25,7 +25,6 @@ const Injector = require("./inject");
 const { BusStore } = require("./store");
 const {
   acquirePollLease,
-  assertFollowPollAllowed,
   releasePollLease,
   runPendingPoll,
 } = require("./poll");
@@ -420,9 +419,10 @@ class EventBus {
   /**
    * Observe pending messages continuously without claiming or acknowledging.
    *
-   * This is an explicit fallback for agent hosts whose own background-task
-   * output is their delivery mechanism. Built-in ufoo agent families keep
-   * using their existing injection/internal-consumption paths.
+   * This is the resident receive path for external agent hosts whose
+   * background-task output wakes the model. The protocol selects wrapper-native
+   * delivery versus MCP registration from UFOO_SUBSCRIBER_ID; agent type names
+   * are not an admission policy for this queue reader.
    */
   async poll(subscriber, options = {}) {
     this.ensureBus();
@@ -432,16 +432,11 @@ class EventBus {
       throw new Error("poll --follow requires <subscriber-id>");
     }
 
-    // Reject known built-in delivery IDs before loading or writing any shared
-    // bus state. This keeps accidental invocation side-effect free for them.
-    assertFollowPollAllowed(target);
-
     this.loadBusData();
     const meta = this.subscriberManager.getSubscriber(target);
     if (!meta) {
       throw new Error(`poll --follow requires a joined subscriber: ${target}`);
     }
-    assertFollowPollAllowed(target, meta);
 
     const intervalSeconds = Number(options.intervalSeconds);
     const intervalMs = Math.max(
@@ -465,10 +460,6 @@ class EventBus {
       this.subscriberManager.updateLastSeen(target);
       this.saveBusData();
 
-      console.log(
-        `[ufoo-poll]<subscriber:${target}> following every ${intervalMs / 1000}s`
-      );
-
       return await runPendingPoll({
         intervalMs,
         signal: options.signal,
@@ -476,7 +467,6 @@ class EventBus {
         maxIterations: options.maxIterations,
         readPending: () => this.queueManager.peekPending(target),
         onEvents: async (events) => {
-          console.log(`[ufoo-poll] ${events.length} new pending event(s)`);
           for (const event of events) {
             const publisherMeta = this.busData.agents?.[event.publisher];
             const nick = publisherMeta?.nickname;

package/src/coordination/bus/poll.js

@@ -3,43 +3,6 @@
 const fs = require("fs");
 const path = require("path");
 
-const BUILTIN_DELIVERY_AGENT_TYPES = new Set([
-  "agy",
-  "antigravity",
-  "claude",
-  "claude-code",
-  "codex",
-  "kimi",
-  "kimi-cli",
-  "kimi-code",
-  "ucode",
-  "ufoo",
-  "ufoo-agent",
-  "ufoo-code",
-]);
-
-function normalizeAgentType(value = "") {
-  return String(value || "").trim().toLowerCase();
-}
-
-function resolveSubscriberAgentType(subscriber, meta = null) {
-  const explicit = normalizeAgentType(meta && meta.agent_type);
-  if (explicit) return explicit;
-  const id = String(subscriber || "").trim();
-  const separator = id.indexOf(":");
-  return normalizeAgentType(separator === -1 ? id : id.slice(0, separator));
-}
-
-function assertFollowPollAllowed(subscriber, meta = null) {
-  const agentType = resolveSubscriberAgentType(subscriber, meta);
-  if (BUILTIN_DELIVERY_AGENT_TYPES.has(agentType)) {
-    throw new Error(
-      `poll --follow is disabled for built-in delivery agent type "${agentType}"`
-    );
-  }
-  return agentType;
-}
-
 function eventIdentity(event = {}) {
   const seq = Number(event && event.seq);
   if (Number.isFinite(seq) && seq > 0) {
@@ -76,6 +39,7 @@ function defaultIsPidAlive(pid) {
 
 function acquirePollLease(pidFile, options = {}) {
   const pid = Number(options.pid) || process.pid;
+  const operation = String(options.operation || "poll --follow");
   const isAlive = typeof options.isAlive === "function"
     ? options.isAlive
     : defaultIsPidAlive;
@@ -90,7 +54,7 @@ function acquirePollLease(pidFile, options = {}) {
       existing = 0;
     }
     if (Number.isFinite(existing) && existing > 0 && isAlive(existing)) {
-      throw new Error(`poll --follow is already running (pid=${existing})`);
+      throw new Error(`${operation} is already running (pid=${existing})`);
     }
     fs.rmSync(pidFile, { force: true });
   }
@@ -101,7 +65,7 @@ function acquirePollLease(pidFile, options = {}) {
     fs.writeFileSync(fd, `${pid}\n`, "utf8");
   } catch (err) {
     if (err && err.code === "EEXIST") {
-      throw new Error("poll --follow is already starting for this subscriber");
+      throw new Error(`${operation} is already starting for this subscriber`);
     }
     throw err;
   } finally {
@@ -179,12 +143,9 @@ async function runPendingPoll(options = {}) {
 }
 
 module.exports = {
-  BUILTIN_DELIVERY_AGENT_TYPES,
   acquirePollLease,
-  assertFollowPollAllowed,
   enumerateEventKeys,
   eventIdentity,
   releasePollLease,
-  resolveSubscriberAgentType,
   runPendingPoll,
 };

package/src/runtime/daemon/controlPlaneService.js

@@ -2,7 +2,13 @@
 
 const crypto = require("crypto");
 const net = require("net");
+const path = require("path");
 const EventBus = require("../../coordination/bus");
+const {
+  acquirePollLease,
+  releasePollLease,
+} = require("../../coordination/bus/poll");
+const { subscriberToSafeName } = require("../../coordination/bus/utils");
 const { normalizeReportInput } = require("../../coordination/report/store");
 const { enqueueAgentReport } = require("./reportControlBus");
 const { isRunning, socketPath } = require("./index");
@@ -12,6 +18,11 @@ const {
   checkAndCleanupNickname,
 } = require("./nicknameScope");
 
+const WAIT_FOR_MESSAGE_DEFAULT_TIMEOUT_SECONDS = 600;
+const WAIT_FOR_MESSAGE_MAX_TIMEOUT_SECONDS = 600;
+const WAIT_FOR_MESSAGE_POLL_INTERVAL_MS = 1000;
+const WAIT_FOR_MESSAGE_HEARTBEAT_INTERVAL_MS = 15000;
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -281,6 +292,181 @@ async function pollInbox(projectRoot, args = {}) {
   };
 }
 
+function waitForMessageCancelledError() {
+  const err = new Error("wait_for_message was cancelled");
+  err.code = "request_cancelled";
+  return err;
+}
+
+function throwIfWaitCancelled(signal) {
+  if (signal && signal.aborted) {
+    throw waitForMessageCancelledError();
+  }
+}
+
+function waitWithSignal(ms, signal) {
+  return new Promise((resolve, reject) => {
+    let timer = null;
+    const onAbort = () => {
+      if (timer) clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      reject(waitForMessageCancelledError());
+    };
+    timer = setTimeout(() => {
+      if (signal) signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function normalizeWaitForMessageArgs(args = {}) {
+  const rawAfterSeq = args.after_seq ?? args.afterSeq ?? 0;
+  const afterSeq = Number(rawAfterSeq);
+  if (!Number.isInteger(afterSeq) || afterSeq < 0) {
+    const err = new Error("wait_for_message after_seq must be a non-negative integer");
+    err.code = "invalid_after_seq";
+    throw err;
+  }
+
+  const rawTimeout = args.timeout_seconds
+    ?? args.timeoutSeconds
+    ?? WAIT_FOR_MESSAGE_DEFAULT_TIMEOUT_SECONDS;
+  const timeoutSeconds = Number(rawTimeout);
+  if (
+    !Number.isFinite(timeoutSeconds)
+    || timeoutSeconds < 1
+    || timeoutSeconds > WAIT_FOR_MESSAGE_MAX_TIMEOUT_SECONDS
+  ) {
+    const err = new Error(
+      `wait_for_message timeout_seconds must be between 1 and ${WAIT_FOR_MESSAGE_MAX_TIMEOUT_SECONDS}`
+    );
+    err.code = "invalid_timeout";
+    throw err;
+  }
+
+  const rawLimit = args.limit ?? 50;
+  const limit = Number(rawLimit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    const err = new Error("wait_for_message limit must be an integer between 1 and 100");
+    err.code = "invalid_limit";
+    throw err;
+  }
+
+  return {
+    afterSeq,
+    timeoutSeconds,
+    limit,
+  };
+}
+
+function eventSeq(event = {}) {
+  const seq = Number(event && event.seq);
+  return Number.isInteger(seq) && seq > 0 ? seq : 0;
+}
+
+function touchWaitingSubscriber(bus, subscriber) {
+  // Long waits span concurrent metadata updates from other agents. Reload
+  // before writing heartbeat state so a stale in-memory registry cannot
+  // overwrite those updates.
+  bus.loadBusData();
+  const meta = assertSubscriberExists(bus, subscriber);
+  meta.status = "active";
+  bus.subscriberManager.updateLastSeen(subscriber);
+  bus.saveBusData();
+}
+
+async function waitForMessage(projectRoot, args = {}, options = {}) {
+  const subscriber = resolveSubscriberArg(args);
+  const { afterSeq, timeoutSeconds, limit } = normalizeWaitForMessageArgs(args);
+  const signal = options.signal || null;
+  const now = typeof options.now === "function" ? options.now : Date.now;
+  const sleep = typeof options.sleep === "function" ? options.sleep : waitWithSignal;
+  const pollIntervalMs = Math.max(
+    50,
+    Number(options.pollIntervalMs) || WAIT_FOR_MESSAGE_POLL_INTERVAL_MS
+  );
+  const heartbeatIntervalMs = Math.max(
+    1000,
+    Number(options.heartbeatIntervalMs) || WAIT_FOR_MESSAGE_HEARTBEAT_INTERVAL_MS
+  );
+  const timeoutMs = timeoutSeconds * 1000;
+
+  const bus = ensureBusLoaded(projectRoot);
+  touchWaitingSubscriber(bus, subscriber);
+  const lease = acquirePollLease(path.join(
+    bus.busDir,
+    "pids",
+    `poll-${subscriberToSafeName(subscriber)}.pid`
+  ), { operation: "wait_for_message" });
+  const cleanupLease = () => releasePollLease(lease);
+  process.once("exit", cleanupLease);
+
+  const startedAt = now();
+  const deadline = startedAt + timeoutMs;
+  let nextHeartbeatAt = startedAt + heartbeatIntervalMs;
+
+  try {
+    while (true) {
+      throwIfWaitCancelled(signal);
+
+      // Queue reads are non-mutating: the Agent acknowledges only after work is
+      // handled, and after_seq suppresses re-delivery within a re-armed wait.
+      // eslint-disable-next-line no-await-in-loop
+      const pending = await bus.queueManager.peekPending(subscriber);
+      const unseen = pending.filter((event) => eventSeq(event) > afterSeq);
+      if (unseen.length > 0) {
+        const messages = unseen.slice(0, limit);
+        const lastSeq = Math.max(afterSeq, ...messages.map(eventSeq));
+        touchWaitingSubscriber(bus, subscriber);
+        return {
+          ok: true,
+          project_root: projectRoot,
+          subscriber,
+          status: "message",
+          timed_out: false,
+          count: messages.length,
+          messages,
+          truncated: unseen.length > messages.length,
+          after_seq: afterSeq,
+          last_seq: lastSeq,
+          waited_ms: Math.max(0, now() - startedAt),
+        };
+      }
+
+      const current = now();
+      if (current >= deadline) {
+        touchWaitingSubscriber(bus, subscriber);
+        return {
+          ok: true,
+          project_root: projectRoot,
+          subscriber,
+          status: "timeout",
+          timed_out: true,
+          count: 0,
+          messages: [],
+          truncated: false,
+          after_seq: afterSeq,
+          last_seq: afterSeq,
+          waited_ms: Math.max(0, current - startedAt),
+        };
+      }
+
+      if (current >= nextHeartbeatAt) {
+        touchWaitingSubscriber(bus, subscriber);
+        nextHeartbeatAt = current + heartbeatIntervalMs;
+      }
+
+      const delayMs = Math.max(1, Math.min(pollIntervalMs, deadline - current));
+      // eslint-disable-next-line no-await-in-loop
+      await sleep(delayMs, signal);
+    }
+  } finally {
+    process.removeListener("exit", cleanupLease);
+    cleanupLease();
+  }
+}
+
 async function reportAgentStatus(projectRoot, args = {}) {
   const subscriber = resolveSubscriberArg(args);
   const report = normalizeReportInput({
@@ -325,6 +511,10 @@ module.exports = {
   publishActivityState,
   updateAgentMetadata,
   pollInbox,
+  waitForMessage,
   reportAgentStatus,
   unregisterAgent,
+  normalizeWaitForMessageArgs,
+  WAIT_FOR_MESSAGE_DEFAULT_TIMEOUT_SECONDS,
+  WAIT_FOR_MESSAGE_MAX_TIMEOUT_SECONDS,
 };

package/src/runtime/daemon/mcpServer.js

@@ -53,7 +53,7 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
   },
   {
     name: "register_agent",
-    description: "Register an externally launched agent into a registered project bus.",
+    description: "Register an externally launched Agent only when its shell has no wrapper-provided UFOO_SUBSCRIBER_ID.",
     input_schema: {
       type: "object",
       required: ["project_root"],
@@ -132,6 +132,34 @@ const CUSTOM_TOOL_DEFINITIONS = Object.freeze([
     },
     handler: handlePollInbox,
   },
+  {
+    name: "wait_for_message",
+    description: "Keep a Codex App-compatible MCP tool call pending until the caller-owned bus queue receives messages after after_seq or the wait reaches its timeout.",
+    input_schema: {
+      type: "object",
+      required: ["project_root", "subscriber"],
+      properties: {
+        project_root: { type: "string" },
+        subscriber: { type: "string" },
+        after_seq: {
+          type: "integer",
+          minimum: 0,
+          default: 0,
+          description: "Return only messages with a sequence greater than this cursor.",
+        },
+        timeout_seconds: {
+          type: "number",
+          minimum: 1,
+          maximum: 600,
+          default: 600,
+          description: "Keep the tool call pending for at most this many seconds.",
+        },
+        limit: { type: "integer", minimum: 1, maximum: 100, default: 50 },
+      },
+      additionalProperties: false,
+    },
+    handler: handleWaitForMessage,
+  },
   {
     name: "report_agent_status",
     description: "Queue an agent task status report through the project daemon report-control queue.",
@@ -416,6 +444,17 @@ async function handlePollInbox(ctx = {}, args = {}) {
   return controlPlane.pollInbox(projectRoot, args);
 }
 
+async function handleWaitForMessage(ctx = {}, args = {}) {
+  const projectRoot = resolveRegisteredProjectRoot(args, ctx);
+  return controlPlane.waitForMessage(projectRoot, args, {
+    signal: ctx.signal,
+    pollIntervalMs: ctx.waitPollIntervalMs,
+    heartbeatIntervalMs: ctx.waitHeartbeatIntervalMs,
+    now: ctx.waitNow,
+    sleep: ctx.waitSleep,
+  });
+}
+
 async function handleReportAgentStatus(ctx = {}, args = {}) {
   const projectRoot = resolveRegisteredProjectRoot(args, ctx);
   return controlPlane.reportAgentStatus(projectRoot, args);
@@ -467,10 +506,15 @@ class UfooMcpServer {
       autoStart: options.autoStart !== false,
       validateProjectRoot: options.validateProjectRoot !== false,
       startTimeoutMs: options.startTimeoutMs,
+      waitPollIntervalMs: options.waitPollIntervalMs,
+      waitHeartbeatIntervalMs: options.waitHeartbeatIntervalMs,
+      waitNow: options.waitNow,
+      waitSleep: options.waitSleep,
     };
     this.initialized = false;
     this.startup = null;
     this.registeredSubscribers = [];
+    this.activeToolCalls = new Map();
   }
 
   async ensureStarted() {
@@ -503,6 +547,11 @@ class UfooMcpServer {
       if (method === "notifications/initialized") {
         this.initialized = true;
       }
+      if (method === "notifications/cancelled") {
+        const requestId = params.requestId;
+        const active = this.activeToolCalls.get(requestId);
+        if (active) active.abort();
+      }
       return null;
     }
 
@@ -541,10 +590,23 @@ class UfooMcpServer {
         if (!name) {
           return createJsonRpcError(id, MCP_ERROR_CODES.INVALID_PARAMS, "tools/call requires params.name");
         }
-        const result = await suppressConsoleToStderr(() => invokeTool(name, args, {
-          ...this.options,
-          toolCallId: id,
-        }));
+        const abortController = new AbortController();
+        this.activeToolCalls.set(id, abortController);
+        let result;
+        try {
+          const runTool = () => invokeTool(name, args, {
+            ...this.options,
+            toolCallId: id,
+            signal: abortController.signal,
+          });
+          // A long-lived wait must not hold the process-global console shim for
+          // up to ten minutes while unrelated MCP calls continue concurrently.
+          result = name === "wait_for_message"
+            ? await runTool()
+            : await suppressConsoleToStderr(runTool);
+        } finally {
+          this.activeToolCalls.delete(id);
+        }
         if (name === "register_agent" && result && result.subscriber && result.project_root) {
           this.registeredSubscribers.push({
             subscriber: result.subscriber,
@@ -570,6 +632,10 @@ class UfooMcpServer {
   }
 
   cleanup() {
+    for (const active of this.activeToolCalls.values()) {
+      active.abort();
+    }
+    this.activeToolCalls.clear();
     for (const { subscriber, projectRoot } of this.registeredSubscribers) {
       try {
         controlPlane.unregisterAgent(projectRoot, { subscriber });

package/src/tools/handlers/ackBus.js

@@ -3,6 +3,9 @@ const { buildToolError, requireSubscriber, getEventBus } = require("./common");
 async function ackBusHandler(ctx = {}, args = {}) {
   const subscriber = requireSubscriber(ctx);
   const requestedSubscriber = String(args.subscriber || subscriber).trim();
+  const rawThroughSeq = args.through_seq ?? args.throughSeq;
+  const hasThroughSeq = rawThroughSeq !== undefined && rawThroughSeq !== null;
+  const throughSeq = hasThroughSeq ? Number(rawThroughSeq) : null;
 
   if (requestedSubscriber !== subscriber) {
     throw buildToolError(
@@ -10,14 +13,23 @@ async function ackBusHandler(ctx = {}, args = {}) {
       "ack_bus can only acknowledge the caller subscriber queue"
     );
   }
+  if (hasThroughSeq && (!Number.isInteger(throughSeq) || throughSeq <= 0)) {
+    throw buildToolError(
+      "invalid_arguments",
+      "ack_bus through_seq must be a positive integer"
+    );
+  }
 
   const eventBus = getEventBus(ctx);
-  const count = await eventBus.ack(subscriber);
+  const count = hasThroughSeq
+    ? await eventBus.ackThrough(subscriber, throughSeq)
+    : await eventBus.ack(subscriber);
 
   return {
     ok: true,
     subscriber,
     acknowledged: count,
+    ...(hasThroughSeq ? { through_seq: throughSeq } : {}),
   };
 }
 

package/src/tools/schemaFixtures.js

@@ -228,6 +228,11 @@ const ACK_BUS_SCHEMA = Object.freeze({
     type: "object",
     properties: Object.freeze({
       subscriber: Object.freeze({ type: "string" }),
+      through_seq: Object.freeze({
+        type: "integer",
+        minimum: 1,
+        description: "Acknowledge only messages up to this sequence, preserving later arrivals.",
+      }),
     }),
     additionalProperties: false,
   }),
@@ -238,6 +243,7 @@ const ACK_BUS_SCHEMA = Object.freeze({
       ok: Object.freeze({ type: "boolean" }),
       subscriber: Object.freeze({ type: "string" }),
       acknowledged: Object.freeze({ type: "integer" }),
+      through_seq: Object.freeze({ type: "integer" }),
     }),
     additionalProperties: false,
   }),