u-foo 3.0.13 → 3.0.14

package/OPTIONAL_SKILLS/ubus-poll/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: ubus-poll
+description: |
+  Explicitly start a resident ufoo bus stream in an agent host that has been
+  configured to deliver streaming background-task output. Install by name only.
+---
+
+# /ubus-poll - Resident Bus Stream
+
+This is an opt-in session-start skill. Run it only in a host where a human has
+configured this fallback. Do not install or invoke it for Codex CLI, Claude
+Code CLI, Agy, Kimi, or native ucode; those runtimes already have their own
+ufoo delivery path.
+
+## Start once per agent session
+
+Reuse the provisioned subscriber identity. Never create a second identity just
+for the poll process.
+
+```bash
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-}"
+test -n "$SUBSCRIBER" || {
+  echo "ubus-poll requires a provisioned UFOO_SUBSCRIBER_ID"
+  exit 1
+}
+```
+
+Identity provisioning is a host/human setup step. Do not guess an agent type,
+call bare `ufoo bus join`, or borrow the workspace's current subscriber.
+
+Use the agent host's **streaming background-task** facility to start:
+
+```bash
+ufoo bus poll "$SUBSCRIBER" --follow --interval 2
+```
+
+The command must remain owned by that facility. Do not use `nohup`, shell `&`,
+or an OS-detached daemon: those routes can put output in a log that never
+reaches the agent. The command rejects a second resident poll for the same
+subscriber.
+
+The poll is deliberately queue-read-only. It emits current pending events at
+startup, waits for that batch to be acknowledged, then emits the next pending
+batch. It does not ack, claim, inject, or clear messages itself.
+
+## When background output arrives
+
+For every `[ufoo]<from:...>` event:
+
+1. Read `Content.message` and execute actionable work.
+2. After handling the emitted batch, run the exact `ack --through <seq>`
+   command printed by the poll stream. For example:
+
+   ```bash
+   ufoo bus ack "$SUBSCRIBER" --through 42
+   ```
+
+   `--through` preserves any later message that was not in the displayed batch.
+
+3. Reply to the sender only for a requested result, an answer, or information
+   they need to continue:
+
+   ```bash
+   ufoo bus send "<sender-id>" "<substantive result>"
+   ```
+
+Ack-only messages, greetings, and thanks need no reply.
+
+After sending, do not poll, sleep, or wait for a reply. Keep working; this
+resident stream will emit any follow-up.
+
+## Host requirement
+
+This flow works only when the agent host forwards incremental output from a
+still-running background task into the agent session. If it only returns output
+after process exit, use an explicitly invoked `/ubus` instead.

package/README.md

@@ -199,6 +199,23 @@ 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:
+
+```bash
+ufoo skills list --optional
+ufoo skills install ubus-poll --target /path/to/that/agent/skills
+ufoo bus poll "$UFOO_SUBSCRIBER_ID" --follow --interval 2
+```
+
+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.
+
 ### Context, Memory, History, Reports
 
 Inside chat:

package/README.zh-CN.md

@@ -193,6 +193,22 @@ ufoo -g
 发送消息前，先用 `/bus status` 查看真实 subscriber ID 或可解析昵称。
 Agent 应处理 pending work、回复发送方，并 ack 自己的队列。
 
+无法接收 ufoo prompt 注入的 Agent host 可以显式启用常驻、队列只读的
+bus 消息流：
+
+```bash
+ufoo skills list --optional
+ufoo skills install ubus-poll --target /path/to/that/agent/skills
+ufoo bus poll "$UFOO_SUBSCRIBER_ID" --follow --interval 2
+```
+
+最后一条命令必须由该 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 类型，确保其现有投递链路不受影响。
+
 ### Context、Memory、History、Report
 
 在 chat 内：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "3.0.13",
+  "version": "3.0.14",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",
@@ -38,6 +38,7 @@
     "scripts/",
     "dist/tui/",
     "SKILLS/",
+    "OPTIONAL_SKILLS/",
     "LICENSE",
     "README.md"
   ],

package/src/app/cli/busCoreCommands.js

@@ -40,17 +40,106 @@ function parseSendArgs(cmdArgs = []) {
 }
 
 function resolvePollSubscriber(cmdArgs = [], env = process.env) {
-  const positionals = cmdArgs.filter((arg) => typeof arg === "string" && !arg.startsWith("--"));
-  const subscriber = String(positionals[0] || env.UFOO_SUBSCRIBER_ID || "").trim();
+  let subscriber = "";
+  let autoAck = false;
+  let follow = false;
+  let intervalSeconds = 2;
+  let intervalWasSet = false;
+
+  for (let index = 0; index < cmdArgs.length; index += 1) {
+    const arg = String(cmdArgs[index] || "");
+    if (arg === "--ack" || arg === "--auto-ack") {
+      autoAck = true;
+      continue;
+    }
+    if (arg === "--follow") {
+      follow = true;
+      continue;
+    }
+    if (arg === "--interval") {
+      const value = cmdArgs[index + 1];
+      if (value === undefined || String(value).startsWith("--")) {
+        throw new Error("poll --interval requires <seconds>");
+      }
+      intervalSeconds = Number(value);
+      intervalWasSet = true;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--interval=")) {
+      intervalSeconds = Number(arg.slice("--interval=".length));
+      intervalWasSet = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown poll option: ${arg}`);
+    }
+    if (subscriber) {
+      throw new Error("poll accepts at most one [subscriber]");
+    }
+    subscriber = arg.trim();
+  }
+
+  subscriber = String(subscriber || env.UFOO_SUBSCRIBER_ID || "").trim();
   if (!subscriber) {
     throw new Error("poll requires [subscriber] or UFOO_SUBSCRIBER_ID");
   }
+  if (follow && autoAck) {
+    throw new Error("poll --follow cannot be combined with --ack");
+  }
+  if (intervalWasSet && !follow) {
+    throw new Error("poll --interval requires --follow");
+  }
+  if (!Number.isFinite(intervalSeconds) || intervalSeconds < 0.25) {
+    throw new Error("poll --interval must be at least 0.25 seconds");
+  }
+
   return {
     subscriber,
-    autoAck: cmdArgs.includes("--ack") || cmdArgs.includes("--auto-ack"),
+    autoAck,
+    follow,
+    intervalSeconds,
   };
 }
 
+function resolveAckArgs(cmdArgs = []) {
+  let subscriber = "";
+  let throughSeq = null;
+
+  for (let index = 0; index < cmdArgs.length; index += 1) {
+    const arg = String(cmdArgs[index] || "");
+    if (arg === "--through") {
+      const value = cmdArgs[index + 1];
+      if (value === undefined || String(value).startsWith("--")) {
+        throw new Error("ack --through requires <seq>");
+      }
+      throughSeq = Number(value);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--through=")) {
+      throughSeq = Number(arg.slice("--through=".length));
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown ack option: ${arg}`);
+    }
+    if (subscriber) {
+      throw new Error("ack accepts exactly one <subscriber>");
+    }
+    subscriber = arg.trim();
+  }
+
+  if (!subscriber) {
+    throw new Error("ack requires <subscriber>");
+  }
+  if (throughSeq !== null && (!Number.isInteger(throughSeq) || throughSeq <= 0)) {
+    throw new Error("ack --through requires a positive integer sequence");
+  }
+
+  return { subscriber, throughSeq };
+}
+
 async function runBusCoreCommand(eventBus, cmd, cmdArgs = []) {
   switch (cmd) {
     case "init":
@@ -91,11 +180,24 @@ async function runBusCoreCommand(eventBus, cmd, cmdArgs = []) {
     case "poll":
       {
         const parsed = resolvePollSubscriber(cmdArgs);
-        await eventBus.check(parsed.subscriber, parsed.autoAck);
+        if (parsed.follow) {
+          await eventBus.poll(parsed.subscriber, {
+            intervalSeconds: parsed.intervalSeconds,
+          });
+        } else {
+          await eventBus.check(parsed.subscriber, parsed.autoAck);
+        }
       }
       return {};
     case "ack":
-      await eventBus.ack(cmdArgs[0]);
+      {
+        const parsed = resolveAckArgs(cmdArgs);
+        if (parsed.throughSeq !== null) {
+          await eventBus.ackThrough(parsed.subscriber, parsed.throughSeq);
+        } else {
+          await eventBus.ack(parsed.subscriber);
+        }
+      }
       return {};
     case "consume":
       await eventBus.consume(cmdArgs[0], cmdArgs.includes("--from-beginning"));
@@ -117,4 +219,8 @@ async function runBusCoreCommand(eventBus, cmd, cmdArgs = []) {
   }
 }
 
-module.exports = { runBusCoreCommand, resolvePollSubscriber };
+module.exports = {
+  resolveAckArgs,
+  resolvePollSubscriber,
+  runBusCoreCommand,
+};

package/src/app/cli/features/skills.js

@@ -8,6 +8,7 @@ class SkillsManager {
   constructor(repoRoot) {
     this.repoRoot = repoRoot;
     this.skillRoots = this.findSkillRoots();
+    this.optionalSkillRoots = this.findOptionalSkillRoots();
   }
 
   /**
@@ -22,13 +23,31 @@ class SkillsManager {
     return roots;
   }
 
+  /**
+   * Optional skills are discoverable and explicitly installable, but are not
+   * included in default listings or `skills install all`.
+   */
+  findOptionalSkillRoots() {
+    const roots = [];
+    const optionalSkills = path.join(this.repoRoot, "OPTIONAL_SKILLS");
+    if (fs.existsSync(optionalSkills)) {
+      roots.push(optionalSkills);
+    }
+    return roots;
+  }
+
   /**
    * 列出所有技能
    */
-  list() {
+  list(options = {}) {
     const skills = new Set();
+    const roots = options.optionalOnly
+      ? this.optionalSkillRoots
+      : (options.includeOptional
+        ? [...this.skillRoots, ...this.optionalSkillRoots]
+        : this.skillRoots);
 
-    for (const root of this.skillRoots) {
+    for (const root of roots) {
       if (!fs.existsSync(root)) {
         continue;
       }
@@ -48,7 +67,7 @@ class SkillsManager {
    * 查找技能路径
    */
   findSkill(name) {
-    for (const root of this.skillRoots) {
+    for (const root of [...this.skillRoots, ...this.optionalSkillRoots]) {
       const skillPath = path.join(root, name);
       if (fs.existsSync(skillPath)) {
         return skillPath;

package/src/app/cli/run.js

@@ -1102,11 +1102,12 @@ async function runCli(argv) {
     skills
       .command("list")
       .description("List available skills")
-      .action(() => {
+      .option("--optional", "List opt-in skills that are not installed by default")
+      .action((opts) => {
         const SkillsManager = require("./features/skills");
         const repoRoot = getPackageRoot();
         const manager = new SkillsManager(repoRoot);
-        const skillsList = manager.list();
+        const skillsList = manager.list({ optionalOnly: Boolean(opts.optional) });
         skillsList.forEach((skill) => console.log(skill));
       });
     skills
@@ -1526,6 +1527,49 @@ async function runCli(argv) {
             process.exitCode = 1;
           });
       });
+    bus
+      .command("poll")
+      .description("Check once, or stream pending messages for an opt-in background task")
+      .argument("[subscriber]", "Subscriber ID (defaults to UFOO_SUBSCRIBER_ID)")
+      .option("--ack", "Acknowledge after a one-shot check")
+      .option("--auto-ack", "Alias for --ack")
+      .option("--follow", "Continuously emit newly observed pending events")
+      .option("--interval <seconds>", "Follow interval in seconds")
+      .action(async (subscriber, opts) => {
+        const EventBus = require("../../coordination/bus");
+        const eventBus = new EventBus(process.cwd());
+        const args = [];
+        if (subscriber) args.push(subscriber);
+        if (opts.ack) args.push("--ack");
+        if (opts.autoAck) args.push("--auto-ack");
+        if (opts.follow) args.push("--follow");
+        if (opts.interval !== undefined) args.push("--interval", String(opts.interval));
+
+        try {
+          await runBusCoreCommand(eventBus, "poll", args);
+        } catch (err) {
+          console.error(err.message);
+          process.exitCode = 1;
+        }
+      });
+    bus
+      .command("ack")
+      .description("Acknowledge pending messages")
+      .argument("<subscriber>", "Subscriber ID")
+      .option("--through <seq>", "Acknowledge only through this displayed sequence")
+      .action(async (subscriber, opts) => {
+        const EventBus = require("../../coordination/bus");
+        const eventBus = new EventBus(process.cwd());
+        const args = [subscriber];
+        if (opts.through !== undefined) args.push("--through", String(opts.through));
+
+        try {
+          await runBusCoreCommand(eventBus, "ack", args);
+        } catch (err) {
+          console.error(err.message);
+          process.exitCode = 1;
+        }
+      });
     bus
       .command("inject")
       .description("Inject /bus into a Terminal.app tab by subscriber ID")
@@ -1695,7 +1739,7 @@ async function runCli(argv) {
     console.log("  ufoo report <start|progress|done|error|list> [message] [--task <id>] [--agent <id>]");
     console.log("  ufoo ucode [doctor|prepare|build] [--skip-install]");
     console.log("  ufoo init [--targets <list>] [--project <dir>]");
-    console.log("  ufoo skills list");
+    console.log("  ufoo skills list [--optional]");
     console.log("  ufoo skills install <name|all> [--target <dir> | --codex | --agents]");
     console.log("  ufoo group templates [list|ls] [--json]");
     console.log("  ufoo group template <list|show|validate|new> [target] [--from <builtin>] [--global] [--force] [--json]");
@@ -1715,7 +1759,8 @@ async function runCli(argv) {
     console.log("  ufoo online send --nickname <name> --text <msg> [--channel <ch>] [--room <id>]");
     console.log("  ufoo online inbox <nickname> [--clear] [--unread]");
     console.log("  ufoo bus wake <target> [--reason <reason>] [--no-shake]");
-    console.log("  ufoo bus poll [subscriber] [--ack]");
+    console.log("  ufoo bus poll [subscriber] [--ack | --follow --interval <seconds>]");
+    console.log("  ufoo bus ack <subscriber> [--through <seq>]");
     console.log("  ufoo bus <args...>    (JS bus implementation)");
     console.log("  ufoo ctx <subcmd> ... (doctor|lint|decisions|sync)");
     console.log("  ufoo history <build|show|prompt> [limit]");
@@ -2056,7 +2101,7 @@ async function runCli(argv) {
     const sub = rest[0] || "";
 
     if (sub === "list") {
-      const skillsList = manager.list();
+      const skillsList = manager.list({ optionalOnly: rest.includes("--optional") });
       skillsList.forEach((skill) => console.log(skill));
       return;
     }

package/src/coordination/bus/index.js

@@ -23,6 +23,12 @@ const MessageManager = require("./message");
 const NicknameManager = require("./nickname");
 const Injector = require("./inject");
 const { BusStore } = require("./store");
+const {
+  acquirePollLease,
+  assertFollowPollAllowed,
+  releasePollLease,
+  runPendingPoll,
+} = require("./poll");
 
 /**
  * Event Bus - 项目级 Agent 事件总线
@@ -411,6 +417,90 @@ class EventBus {
     return pending;
   }
 
+  /**
+   * 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.
+   */
+  async poll(subscriber, options = {}) {
+    this.ensureBus();
+
+    const target = String(subscriber || "").trim();
+    if (!target) {
+      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(
+      250,
+      Number.isFinite(intervalSeconds) ? intervalSeconds * 1000 : 2000
+    );
+    const pollPidFile = path.join(
+      this.busDir,
+      "pids",
+      `poll-${subscriberToSafeName(target)}.pid`
+    );
+    const lease = acquirePollLease(pollPidFile, { isAlive: isPidAlive });
+    const cleanupLease = () => releasePollLease(lease);
+    process.once("exit", cleanupLease);
+
+    try {
+      // The resident poll process owns liveness for this explicitly opted-in
+      // subscriber. No notifier/injector state is touched.
+      meta.status = "active";
+      meta.pid = process.pid;
+      this.subscriberManager.updateLastSeen(target);
+      this.saveBusData();
+
+      console.log(
+        `[ufoo-poll]<subscriber:${target}> following every ${intervalMs / 1000}s`
+      );
+
+      return await runPendingPoll({
+        intervalMs,
+        signal: options.signal,
+        sleep: options.sleep,
+        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;
+            const fromLabel = nick ? `${event.publisher}(${nick})` : event.publisher;
+            console.log(`[ufoo]<from:${fromLabel || "unknown"}>`);
+            console.log(`Type: ${event.type}/${event.event}`);
+            console.log(`Content: ${JSON.stringify(event.data)}`);
+          }
+          const sequenced = events
+            .map((event) => Number(event && event.seq))
+            .filter((seq) => Number.isFinite(seq) && seq > 0);
+          const throughSeq = sequenced.length === events.length
+            ? Math.max(...sequenced)
+            : 0;
+          const ackSuffix = throughSeq > 0 ? ` --through ${throughSeq}` : "";
+          console.log(`After handling, run: ufoo bus ack ${target}${ackSuffix}`);
+        },
+      });
+    } finally {
+      process.removeListener("exit", cleanupLease);
+      cleanupLease();
+    }
+  }
+
   /**
    * 确认消息
    */
@@ -429,6 +519,24 @@ class EventBus {
     return count;
   }
 
+  /**
+   * Confirm only the displayed portion of a sequenced pending queue.
+   */
+  async ackThrough(subscriber, throughSeq) {
+    this.ensureBus();
+    this.loadBusData();
+
+    const count = await this.messageManager.ackThrough(subscriber, throughSeq);
+
+    if (count > 0) {
+      logOk(`Acknowledged ${count} message(s) through seq=${throughSeq}`);
+    } else {
+      logOk(`No pending messages through seq=${throughSeq}`);
+    }
+
+    return count;
+  }
+
   /**
    * 消费事件
    */

package/src/coordination/bus/message.js

@@ -529,6 +529,10 @@ class MessageManager {
     return this.queueManager.ackPending(subscriber);
   }
 
+  async ackThrough(subscriber, throughSeq) {
+    return this.queueManager.ackPendingThrough(subscriber, throughSeq);
+  }
+
   /**
    * 消费事件（从 offset 开始）
    */

package/src/coordination/bus/poll.js

@@ -0,0 +1,190 @@
+"use strict";
+
+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) {
+    return `seq:${seq}`;
+  }
+  return `event:${JSON.stringify(event || {})}`;
+}
+
+function enumerateEventKeys(events = []) {
+  const occurrences = new Map();
+  return events.map((event) => {
+    const identity = eventIdentity(event);
+    const occurrence = occurrences.get(identity) || 0;
+    occurrences.set(identity, occurrence + 1);
+    return {
+      event,
+      key: `${identity}#${occurrence}`,
+    };
+  });
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function defaultIsPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return Boolean(err && err.code === "EPERM");
+  }
+}
+
+function acquirePollLease(pidFile, options = {}) {
+  const pid = Number(options.pid) || process.pid;
+  const isAlive = typeof options.isAlive === "function"
+    ? options.isAlive
+    : defaultIsPidAlive;
+
+  fs.mkdirSync(path.dirname(pidFile), { recursive: true });
+
+  if (fs.existsSync(pidFile)) {
+    let existing = 0;
+    try {
+      existing = Number.parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+    } catch {
+      existing = 0;
+    }
+    if (Number.isFinite(existing) && existing > 0 && isAlive(existing)) {
+      throw new Error(`poll --follow is already running (pid=${existing})`);
+    }
+    fs.rmSync(pidFile, { force: true });
+  }
+
+  let fd;
+  try {
+    fd = fs.openSync(pidFile, "wx");
+    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 err;
+  } finally {
+    if (typeof fd === "number") fs.closeSync(fd);
+  }
+
+  return { pid, pidFile };
+}
+
+function releasePollLease(lease) {
+  if (!lease || !lease.pidFile) return false;
+  try {
+    const existing = Number.parseInt(
+      fs.readFileSync(lease.pidFile, "utf8").trim(),
+      10
+    );
+    if (existing !== lease.pid) return false;
+    fs.rmSync(lease.pidFile, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function runPendingPoll(options = {}) {
+  const readPending = options.readPending;
+  const onEvents = options.onEvents;
+  const sleep = options.sleep || defaultSleep;
+  const signal = options.signal || null;
+  const intervalMs = Math.max(250, Number(options.intervalMs) || 2000);
+  const maxIterations = Number.isFinite(options.maxIterations)
+    ? Math.max(0, Math.floor(options.maxIterations))
+    : Infinity;
+
+  if (typeof readPending !== "function") {
+    throw new Error("runPendingPoll requires readPending");
+  }
+  if (typeof onEvents !== "function") {
+    throw new Error("runPendingPoll requires onEvents");
+  }
+  if (maxIterations === 0) {
+    return { iterations: 0 };
+  }
+
+  let inFlightKeys = new Set();
+  let iterations = 0;
+
+  while (!signal || !signal.aborted) {
+    // eslint-disable-next-line no-await-in-loop
+    const pending = await readPending();
+    const keyed = enumerateEventKeys(Array.isArray(pending) ? pending : []);
+    const currentKeys = new Set(keyed.map((entry) => entry.key));
+    const hasUnacknowledgedBatch = Array.from(inFlightKeys)
+      .some((key) => currentKeys.has(key));
+
+    if (!hasUnacknowledgedBatch) {
+      inFlightKeys = new Set();
+    }
+
+    if (inFlightKeys.size === 0 && keyed.length > 0) {
+      const batch = keyed.map((entry) => entry.event);
+      // eslint-disable-next-line no-await-in-loop
+      await onEvents(batch);
+      inFlightKeys = currentKeys;
+    }
+
+    iterations += 1;
+    if (iterations >= maxIterations || (signal && signal.aborted)) break;
+
+    // eslint-disable-next-line no-await-in-loop
+    await sleep(intervalMs);
+  }
+
+  return { iterations };
+}
+
+module.exports = {
+  BUILTIN_DELIVERY_AGENT_TYPES,
+  acquirePollLease,
+  assertFollowPollAllowed,
+  enumerateEventKeys,
+  eventIdentity,
+  releasePollLease,
+  resolveSubscriberAgentType,
+  runPendingPoll,
+};

package/src/coordination/bus/queue.js

@@ -5,7 +5,11 @@ const {
   ensureDir,
   truncateFile,
 } = require("./utils");
-const { DeliveryQueue, stripQueueEnvelope } = require("./deliveryQueue");
+const {
+  DeliveryQueue,
+  positiveSeq,
+  stripQueueEnvelope,
+} = require("./deliveryQueue");
 
 /**
  * 队列管理器
@@ -87,6 +91,15 @@ class QueueManager {
     return this.getDeliveryQueue(subscriber).readPending().map(stripQueueEnvelope);
   }
 
+  /**
+   * Non-mutating pending read for opt-in background observers.
+   *
+   * Unlike readPending(), this deliberately does not recover stale claims.
+   */
+  async peekPending(subscriber) {
+    return this.getDeliveryQueue(subscriber).readPendingRaw().map(stripQueueEnvelope);
+  }
+
   /**
    * 追加待处理消息
    */
@@ -122,6 +135,36 @@ class QueueManager {
     return count;
   }
 
+  /**
+   * Acknowledge only sequenced events up to and including throughSeq.
+   *
+   * Later arrivals remain pending, which prevents a background poll consumer
+   * from clearing messages that were not part of the emitted batch.
+   */
+  async ackPendingThrough(subscriber, throughSeq) {
+    const limit = Number(throughSeq);
+    if (!Number.isFinite(limit) || limit <= 0) {
+      throw new Error("ack --through requires a positive sequence");
+    }
+
+    const deliveryQueue = this.getDeliveryQueue(subscriber);
+    let count = 0;
+    while (true) {
+      const claim = deliveryQueue.claimNext();
+      if (!claim) break;
+
+      const seq = positiveSeq(claim.event);
+      if (seq === 0 || seq > limit) {
+        deliveryQueue.restoreClaim(claim);
+        break;
+      }
+
+      deliveryQueue.completeClaim(claim);
+      count += 1;
+    }
+    return count;
+  }
+
   /**
    * 检查是否有待处理消息
    */