dsh-handoff-bus 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.1.1 — 2026-10-19
+
+### Fixed — instructions piling up
+
+Each delivery becomes its own turn in the target conversation, so a burst of `指令`
+made the target execute obsolete commands one after another while the task file had
+already moved on. Two changes:
+
+- **Instruction back-pressure**: a second `指令` to the same target is refused with
+  `instruction_pending` while the previous one has no `回报` yet. Update the task file
+  and wait for the report, or pass `force: true`. Bounded by `pendingInstructionTtlSec`
+  (default 600s), so a target that never reports does not block forever. Notices and
+  requests are not affected.
+- **Self-identifying messages**: every `指令` footer now carries its per-pair sequence
+  ("本线第 N 条指令") and tells the receiver to compare it with `bus_list.latest`; a
+  message whose `seq` is below the latest is stale and should not be executed.
+
+`bus_list` additionally returns `latest`: the newest instruction per role pair, with
+`seq`, `ref`, and `awaitingReport`. Both the counter and the pending state are rebuilt
+from `deliveries.jsonl`, so they survive a client restart without another state file.
+
+New config keys: `blockSecondInstruction` (default `true`), `pendingInstructionTtlSec`
+(default `600`). New `bus_send` parameter: `force`.
+
+### Fixed — documentation
+
+- `target_unresolvable` now says the target may also be "owned by subagent routing", and states that only a top-level GUI conversation can be a target.
+- `bus_send` tool description documents the subagent restriction and that `ref` is passed through verbatim.
+- The protocol line appended to `指令` messages now suggests `R-` numbering (e.g. `R-001`) for reports.
+- README (both languages): documented the subagent restriction, the `ref` convention, the instruction back-pressure, and a token-budget section.
+
 ## 0.1.0 — 2026-10-18
 
 - Initial public release.

package/README.md

@@ -16,6 +16,7 @@ A small host plugin for [DeepSeek Harness](https://www.deepseek.com/harness/) (D
 - ❌ No file watching, no timers, no autonomous work when you are away
 - ❌ It does not replace your state files: task files and reports are still written by the conversations; the bus only delivers pointers and wakes the target
 - ❌ No cross-workspace addressing (one bus per workspace)
+- ❌ No addressing of subagent sessions: only a **top-level GUI conversation** can be a target. A session running as a subagent under another agent is owned by the host router; registering it from inside does not make it reachable, and `bus_send` answers `target_unresolvable`
 
 ## How it works
 
@@ -75,6 +76,8 @@ dsh plugin --profile <profile> add dsh-handoff-bus
 
 Role names are arbitrary strings you choose; `worker-a` / `worker-b` are only examples.
 
+`ref` is passed through verbatim — nothing validates its format. The convention in the examples is `D-` for instructions and `R-` for reports (`Q-` for status requests), numbered per project. Pick one scheme and keep it consistent; it only lands in the message header, so the receiving conversation is what gives it meaning.
+
 | Situation | Call |
 |---|---|
 | Main gives work to a sub | `bus_send(target="worker-a", kind="指令", ref="D-001", message="…")` |
@@ -82,6 +85,55 @@ Role names are arbitrary strings you choose; `worker-a` / `worker-b` are only ex
 | Main asks for status (no work) | `bus_send(target="worker-a", kind="请求", ref="Q-…", message="Status only, do not start work.")` |
 | Queue without waking | add `"wake": false` |
 
+## Delivering without piling up
+
+Every delivery is a separate turn in the target conversation. If `main` sends three
+`指令` to `worker-a` in a row while `worker-a` is still working, all three queue up and
+are executed in order — the first one runs against a task file that is already at
+version three. Three consequences:
+
+- **A second `指令` is refused** while the previous one has no `回报`
+  (`instruction_pending`). Update the task file, wait for the report, then dispatch
+  again; `force: true` overrides when you really mean to queue.
+- **Each `指令` carries its own sequence** ("本线第 3 条指令") and the footer tells the
+  receiver to compare it with `bus_list.latest`. A `seq` below the latest means the
+  message was superseded: do the newest one, skip the duplicate work.
+- **The counter and the pending state are rebuilt from `deliveries.jsonl`**, so a client
+  restart neither resets the numbering nor forgets an unanswered instruction.
+
+A sub-conversation prompt that makes this reliable:
+
+```text
+收到 [BUS 指令] 后，先调用 bus_list 看 latest 里「main->自己角色」的 seq。
+如果消息末尾写的「本线第 N 条」小于 seq，说明已被后面的指令取代：
+只做最新那条，不要重复劳动，并在回报里说明跳过了哪一条。
+```
+
+## Token cost
+
+The bus itself is cheap; the turns it triggers are not.
+
+| Item | Cost |
+|---|---|
+| Tool schemas (4 tools) | ~700 tokens per request, in every conversation, used or not |
+| Message wrapper | ~120 tokens per delivered message (header, workspace, time, protocol lines) |
+| **A woken turn** | **the target's whole context, re-sent as input** |
+
+The third row dominates. Waking a conversation that already holds 30k tokens of history
+costs 30k input tokens for a 20-character message — and the message stays in that
+history, so every later turn of that session is slightly more expensive as well.
+
+Ways to spend less:
+
+1. **Batch.** Update the task file, then send one `指令`, not four.
+2. **`wake: false`** for anything that is not a "start working now" signal: it lands in
+   the inbox and costs nothing until the target runs on its own.
+3. **Keep sub-conversation sessions short.** Wake cost = that session's context length,
+   so a line that has been running for hours is the expensive one. Finish a milestone,
+   open a fresh conversation, `bus_register` again.
+4. **Pointers, not payloads.** Summary + file path in the body; the report stays in the file.
+5. **Disable the plugin in profiles that never use it** — that removes the ~700-token schema.
+
 ## New workspace setup (copy-paste prompt)
 
 The bus does not create directories or write task files. In a new workspace:
@@ -142,8 +194,8 @@ bus_send(target="main", kind="回报", ref="R-<date>-01", message="Report writte
 |---|---|
 | `bus_register(role, note?)` | Register this conversation as a role **in its workspace** |
 | `bus_whoami()` | Current role + workspace |
-| `bus_list()` | All roles **in this workspace** → sessionId / bound time |
-| `bus_send(target, message, kind?, ref?, wake?)` | Deliver to a role in this workspace; `wake=true` wakes it |
+| `bus_list()` | All roles **in this workspace** → sessionId / bound time, plus `latest` (newest `指令` per pair with `seq` / `awaitingReport`) |
+| `bus_send(target, message, kind?, ref?, wake?, force?)` | Deliver to a role in this workspace; `wake=true` wakes it, `force=true` overrides instruction back-pressure |
 
 `kind`: `指令` (instruction), `回报` (report), `通知` (notice), `请求` (request). These four values are literal tokens — keep them in Chinese; do not translate them.
 
@@ -163,7 +215,9 @@ Example `config.json`:
   "stateDirName": ".bus",
   "maxMessageChars": 4000,
   "maxSendsPerHour": 30,
-  "maxPairSendsPer10Min": 8
+  "maxPairSendsPer10Min": 8,
+  "blockSecondInstruction": true,
+  "pendingInstructionTtlSec": 600
 }
 ```
 
@@ -177,6 +231,8 @@ Example `config.json`:
 | `maxMessageChars` | 4000 | Per-message limit |
 | `maxSendsPerHour` | 30 | Per-conversation hourly limit |
 | `maxPairSendsPer10Min` | 8 | Per role-pair limit, to stop ping-pong |
+| `blockSecondInstruction` | `true` | Refuse a `指令` while the previous one to the same target has no `回报` yet |
+| `pendingInstructionTtlSec` | 600 | After this long without a `回报`, the pending instruction stops blocking |
 
 `deliveries.jsonl` is append-only. Delete it manually if it grows; automatic rotation is planned for a later release.
 
@@ -190,8 +246,9 @@ Example `config.json`:
 | `caller_not_registered` | This conversation has no role yet |
 | `target_not_registered` | The target role does not exist in this workspace |
 | `self_target` | The target is this conversation |
-| `target_unresolvable` | The target session cannot be opened (archived/deleted) |
+| `target_unresolvable` | The target session cannot be opened (archived/deleted, or owned by subagent routing) |
 | `rate_limited` | Rate limit hit |
+| `instruction_pending` | A `指令` to this target is still unanswered; wait for the `回报`, or pass `force: true` |
 | `flush_failed` | Queued but persistence was not acknowledged |
 | `delivery_failed` | Delivery error |
 | `aborted` | The tool call was cancelled |

package/README.zh.md

@@ -16,6 +16,7 @@
 - ❌ 不监听文件、不设定时任务、不在你不在场时自动开工
 - ❌ 不替代你的状态文件：任务文件、回报仍由对话自己写，总线只负责送达和叫醒
 - ❌ 不跨工作区寻址（每个目录一条总线）
+- ❌ 不能向子代理会话发送消息：目标必须是**顶层 GUI 会话**。作为 subagent 跑在别的会话下面的会话由宿主路由接管，在里面注册也发不进去，`bus_send` 会返回 `target_unresolvable`
 
 ## 工作流
 
@@ -68,6 +69,8 @@ dsh plugin --profile <profile> add dsh-handoff-bus
 
 角色名是任意字符串，`worker-a` / `worker-b` 只是示例。
 
+`ref` 原样透传，工具不校验格式。示例里的约定是：指令用 `D-`、回报用 `R-`、状态询问用 `Q-`，后面跟项目内的编号。你选一套保持前后一致即可 —— 它只会出现在消息头里，含义由接收方按约定理解。
+
 | 用途 | 调用 |
 |---|---|
 | 主 → 子派活 | `bus_send(target="worker-a", kind="指令", ref="D-001", message="…")` |
@@ -75,6 +78,44 @@ dsh plugin --profile <profile> add dsh-handoff-bus
 | 主问进度（不派活） | `bus_send(target="worker-a", kind="请求", ref="Q-…", message="只回当前状态，不要开工")` |
 | 只想排队、不叫醒 | 加 `"wake": false` |
 
+## 防止指令堆积
+
+每一次投递，都会在目标会话里单独变成一个 turn。主对话在子线还在干活时连发三条指令，
+三条都会排队，然后按顺序依次执行 —— 第一条跑的时候，任务文件早就到第三版了。所以：
+
+- **上一条指令没回报时，第二条会被拒绝**（`instruction_pending`）。正确做法是更新任务文件、等回报、再下发；确实要排队就加 `force: true`。
+- **每条指令自带序号**（消息末尾的「本线第 3 条指令」），并提示接收方用 `bus_list` 的 `latest` 对照。序号小于最新的，说明已被取代：只做最新那条，不要重复劳动。
+- **计数和「待回报」状态都从 `deliveries.jsonl` 重放**，所以重启客户端既不会把编号清零，也不会忘掉一条还没回报的指令。
+
+配套的子对话提示词（推荐写进子线的开场指令里）：
+
+```text
+收到 [BUS 指令] 后，先调用 bus_list 看 latest 里「main->自己角色」的 seq。
+如果消息末尾写的「本线第 N 条」小于 seq，说明已被后面的指令取代：
+只做最新那条，不要重复劳动，并在回报里说明跳过了哪一条。
+```
+
+## Token 开销
+
+总线本身很便宜，它触发的 turn 才是花钱的地方。
+
+| 项目 | 成本 |
+|---|---|
+| 四个工具的定义 | **每次请求**约 700 token，所有会话都带，用不用都算 |
+| 消息包装 | 每条约 120 token（消息头、工作区、时间、协议句） |
+| **被唤醒的一个 turn** | **目标会话的整个上下文重新作为输入送一遍** |
+
+真正贵的是第三行。一个已经积累 3 万 token 的会话，被叫醒来读一条 20 字的消息，这次唤醒就要
+3 万输入 token；而且这条消息会永久留在它的历史里，这个会话之后每一轮都会略贵一点。
+
+省 token 的五个做法：
+
+1. **攒批**：先更新任务文件，再发**一条**指令，而不是连发四条。
+2. **`wake: false`**：不是「立刻开工」的消息就别叫醒，塞进收件箱，等它自己下次跑。
+3. **子线会话别开太久**：唤醒成本 = 该会话的上下文长度，跑了几小时的那条线就是最贵的。做完一个阶段就新开一个会话，重新 `bus_register`。
+4. **只发指针**：正文给摘要 + 文件路径，正文内容留在文件里。
+5. **不用的 profile 直接禁用插件**：那 700 token 的 schema 就不带了。
+
 ## 新目录开工（发给主对话的提示词）
 
 总线不建目录、不写任务文件。新目录第一次用时：
@@ -132,8 +173,8 @@ bus_send(target="main", kind="回报", ref="R-<日期>-01", message="回报已
 |---|---|
 | `bus_register(role, note?)` | 把当前会话注册为**本工作区**的角色 |
 | `bus_whoami()` | 当前会话的角色 + 工作区 |
-| `bus_list()` | 列出**本工作区**所有角色 → sessionId / 绑定时间 |
-| `bus_send(target, message, kind?, ref?, wake?)` | 投递到本工作区目标；`wake=true` 默认唤醒 |
+| `bus_list()` | 列出**本工作区**所有角色 → sessionId / 绑定时间，并附 `latest`（每对角色最新一条指令的 `seq` 与是否仍未回报） |
+| `bus_send(target, message, kind?, ref?, wake?, force?)` | 投递到本工作区目标；`wake=true` 默认唤醒，`force=true` 跳过指令堆积拦截 |
 
 `kind`：`指令`、`回报`、`通知`、`请求`（固定字面量，不要翻译）。
 
@@ -153,7 +194,9 @@ bus_send(target="main", kind="回报", ref="R-<日期>-01", message="回报已
   "stateDirName": ".bus",
   "maxMessageChars": 4000,
   "maxSendsPerHour": 30,
-  "maxPairSendsPer10Min": 8
+  "maxPairSendsPer10Min": 8,
+  "blockSecondInstruction": true,
+  "pendingInstructionTtlSec": 600
 }
 ```
 
@@ -167,6 +210,8 @@ bus_send(target="main", kind="回报", ref="R-<日期>-01", message="回报已
 | `maxMessageChars` | 4000 | 单条消息上限 |
 | `maxSendsPerHour` | 30 | 每会话每小时上限 |
 | `maxPairSendsPer10Min` | 8 | 同一对角色 10 分钟上限 |
+| `blockSecondInstruction` | `true` | 上一条指令还没回报时，拒绝对同一目标再下指令 |
+| `pendingInstructionTtlSec` | 600 | 超过这个时间没回报，就不再拦 |
 
 `deliveries.jsonl` 只追加；长期使用会变大，可手动删除，自动轮转在后续版本加。
 
@@ -180,8 +225,9 @@ bus_send(target="main", kind="回报", ref="R-<日期>-01", message="回报已
 | `caller_not_registered` | 本会话还没注册角色 |
 | `target_not_registered` | 目标角色在本工作区不存在 |
 | `self_target` | 目标就是自己 |
-| `target_unresolvable` | 目标会话无法打开（归档/删除等） |
+| `target_unresolvable` | 目标会话无法打开（已归档/删除，或被 subagent 路由占用） |
 | `rate_limited` | 触发限流 |
+| `instruction_pending` | 上一条指令还没回报；等回报，或加 `force: true` |
 | `flush_failed` | 已入队但持久化未确认 |
 | `delivery_failed` | 投递异常 |
 | `aborted` | 工具调用被取消 |

package/config.example.json

@@ -3,5 +3,7 @@
   "stateDirName": ".bus",
   "maxMessageChars": 4000,
   "maxSendsPerHour": 30,
-  "maxPairSendsPer10Min": 8
+  "maxPairSendsPer10Min": 8,
+  "blockSecondInstruction": true,
+  "pendingInstructionTtlSec": 600
 }

package/index.js

@@ -29,6 +29,11 @@
  *  - Delivery resolves the target Session through the Host session controller
  *    and appends a user-role message to its inbox; `wake: true` (default)
  *    also wakes it.
+ *  - Instructions are back-pressured: each delivery becomes its own turn in the
+ *    target, so a queued 指令 is still executed after a newer one arrives. A second
+ *    指令 is therefore refused while the previous one has no 回报 (`instruction_pending`),
+ *    unless the caller passes `force: true`. Every 指令 also carries its per-pair
+ *    sequence, so a superseded message can identify itself via `bus_list.latest`.
  *
  * The delivery path mirrors the shipped `dsh-schedule` package:
  *   ctx.sessionController.resolveAgent(sessionId) -> agent.followup(message)
@@ -54,6 +59,15 @@ const DEFAULT_CONFIG = {
   maxMessageChars: 4000,
   maxSendsPerHour: 30,
   maxPairSendsPer10Min: 8,
+  /**
+   * Refuse a second 指令 to the same target while the previous one has not been
+   * answered with a 回报. Each delivery becomes its own turn, so a burst of
+   * instructions makes the target execute obsolete commands one by one.
+   * Override per call with `force: true`.
+   */
+  blockSecondInstruction: true,
+  /** After this long without a 回报, the pending instruction stops blocking. */
+  pendingInstructionTtlSec: 600,
 }
 
 /** Standard JSON Schema shared by all four tools; every result carries `ok`. */
@@ -74,6 +88,9 @@ const OUTPUT_SCHEMA = {
     sentAt: { type: 'string' },
     woken: { type: 'boolean' },
     replaced: { type: 'string' },
+    warning: { type: 'string' },
+    seq: { type: 'number' },
+    latest: { type: 'object' },
     roles: {
       type: 'array',
       items: {
@@ -200,16 +217,54 @@ export function apply(ctx, config) {
     return { version: 1, roles: {} }
   }
 
+  /**
+   * Delivery log is metadata-only and append-only; replaying it at startup is
+   * how the per-pair instruction counter and the "still awaiting a 回报" state
+   * survive a client restart without another state file.
+   */
+  function replayDeliveries(file) {
+    const state = { seq: new Map(), lastInstruction: new Map(), lastReport: new Map() }
+    let raw
+    try {
+      raw = fs.readFileSync(file, 'utf8')
+    } catch {
+      return state
+    }
+    for (const line of raw.split('\n')) {
+      if (line.trim().length === 0) continue
+      let entry
+      try {
+        entry = JSON.parse(line)
+      } catch {
+        continue
+      }
+      if (!entry || typeof entry.fromRole !== 'string' || typeof entry.toRole !== 'string') continue
+      if (typeof entry.at !== 'string') continue
+      const pair = `${entry.fromRole}->${entry.toRole}`
+      if (entry.kind === '指令') {
+        const next = (state.seq.get(pair) ?? 0) + 1
+        state.seq.set(pair, next)
+        state.lastInstruction.set(pair, { seq: next, at: entry.at, ref: entry.ref })
+      } else if (entry.kind === '回报') {
+        // A report from B to A acknowledges A's last instruction to B.
+        state.lastReport.set(`${entry.toRole}->${entry.fromRole}`, entry.at)
+      }
+    }
+    return state
+  }
+
   function busFor(workspace) {
     const existing = buses.get(workspace)
     if (existing) return existing
     const dir = stateDirFor(workspace)
+    const deliveriesPath = path.join(dir, 'deliveries.jsonl')
     const bus = {
       workspace,
       dir,
       bindingsPath: path.join(dir, 'bindings.json'),
-      deliveriesPath: path.join(dir, 'deliveries.jsonl'),
+      deliveriesPath,
       bindings: readBindings(path.join(dir, 'bindings.json')),
+      state: replayDeliveries(deliveriesPath),
       sendTimes: new Map(), // callerSessionId -> number[]
       pairTimes: new Map(), // "fromRole->toRole" -> number[]
     }
@@ -217,6 +272,17 @@ export function apply(ctx, config) {
     return bus
   }
 
+  /** Instruction that was sent to `toRole` and never acknowledged by a 回报. */
+  function pendingInstruction(bus, fromRole, toRole) {
+    const pair = `${fromRole}->${toRole}`
+    const last = bus.state.lastInstruction.get(pair)
+    if (!last) return undefined
+    const ackedAt = bus.state.lastReport.get(pair)
+    if (ackedAt && Date.parse(ackedAt) >= Date.parse(last.at)) return undefined
+    if (Date.now() - Date.parse(last.at) > cfg.pendingInstructionTtlSec * 1000) return undefined
+    return last
+  }
+
   // ---------------------------------------------------------------- bindings
 
   function writeBindings(bus) {
@@ -254,6 +320,24 @@ export function apply(ctx, config) {
       .sort((a, b) => a.role.localeCompare(b.role))
   }
 
+  /**
+   * Latest instruction per role pair. A woken conversation compares the `seq`
+   * in its message footer against this to see whether it was superseded.
+   */
+  function latestInstructions(bus) {
+    const out = {}
+    for (const [pair, info] of bus.state.lastInstruction) {
+      const [fromRole, toRole] = pair.split('->')
+      out[pair] = {
+        seq: info.seq,
+        ...(info.ref ? { ref: info.ref } : {}),
+        at: info.at,
+        awaitingReport: pendingInstruction(bus, fromRole, toRole) !== undefined,
+      }
+    }
+    return out
+  }
+
   // ---------------------------------------------------------------- delivery
 
   function appendDelivery(bus, entry) {
@@ -282,7 +366,7 @@ export function apply(ctx, config) {
     return { ok: true }
   }
 
-  function composeBusText({ workspace, fromRole, toRole, kind, ref, message }) {
+  function composeBusText({ workspace, fromRole, toRole, kind, ref, message, seq }) {
     const lines = [
       `[BUS ${kind}] ${fromRole} → ${toRole}${ref ? ` · ${ref}` : ''}`,
       `工作区：${workspace}`,
@@ -294,7 +378,11 @@ export function apply(ctx, config) {
       '权威状态仍以 handoff/ 对应文件为准；本条只负责送达和提醒。',
     ]
     if (kind === '指令') {
-      lines.push(`执行完后用 bus_send 回报「${fromRole}」（kind=回报，ref 带指令编号）；不要自动回执，也不要转发给其他线。`)
+      lines.push(
+        `本线第 ${seq} 条指令。动手前先用 bus_list 核对本线最新编号：若最新编号大于 ${seq}，` +
+          `说明后面还有新指令，本条按过期处理，只做最新那条，不要重复劳动。` +
+          `完成后 bus_send 回报「${fromRole}」（kind=回报，ref 用 R- 编号，如 R-001）；不要自动回执，也不要转发给其他线。`,
+      )
     } else if (kind === '回报') {
       lines.push('收到回报后按协议更新你们的状态文件；需要继续时再用 bus_send 下达指令。')
     } else {
@@ -387,7 +475,9 @@ export function apply(ctx, config) {
     name: 'bus_list',
     description:
       'List every role currently bound in this conversation\'s workspace, with its sessionId and binding time. ' +
-      'Use it to check which target names bus_send accepts. Other workspaces have their own independent tables.',
+      'Use it to check which target names bus_send accepts. Other workspaces have their own independent tables. ' +
+      'Also returns `latest`: the newest 指令 per role pair (with its seq and whether a 回报 is still outstanding), ' +
+      'so a woken conversation can tell whether the message in front of it has already been superseded.',
     parameters: { type: 'object', additionalProperties: false, properties: {} },
     async execute(_args, exec) {
       const sessionId = exec?.agent?.session?.id
@@ -400,6 +490,7 @@ export function apply(ctx, config) {
         workspace,
         caller: roleOfSession(bus, sessionId) ?? '',
         roles: listRoles(bus),
+        latest: latestInstructions(bus),
       }
     },
   })
@@ -412,8 +503,12 @@ export function apply(ctx, config) {
       'a sub-conversation uses it to report back (target = main). ' +
       'The target sees the message as a user message starting with "[BUS ...]". ' +
       'Roles are scoped to the workspace; a role registered in another directory is not addressable from here. ' +
+      'The target must be a top-level GUI conversation the host can reopen; a session running as a subagent under another agent cannot be a target. ' +
       'Put only the summary and the handoff file pointers in the body; write authoritative state to the files first. ' +
-      'Use ref for the instruction/report id (e.g. D-001 / R-001). ' +
+      'Use ref for the instruction/report id (e.g. D-001 / R-001); it is passed through verbatim and not validated. ' +
+      'A second 指令 to the same target is refused while the previous one has not been answered with a 回报 ' +
+      '(each delivery costs the target a whole turn, so a burst makes it execute obsolete instructions). ' +
+      'Update the task file and wait for the report instead; pass force=true to override. ' +
       'Set wake=false to queue the message without starting a turn.',
     parameters: {
       type: 'object',
@@ -439,6 +534,10 @@ export function apply(ctx, config) {
           type: 'boolean',
           description: 'Wake the target into a new turn (default true). false = queue only.',
         },
+        force: {
+          type: 'boolean',
+          description: 'Send a 指令 even though the previous one has not been answered with a 回报 yet.',
+        },
       },
       required: ['target', 'message'],
     },
@@ -478,6 +577,22 @@ export function apply(ctx, config) {
       }
       const ref = nonEmptyString(args.ref) ? args.ref.trim() : ''
       const wantWake = args.wake !== false
+      const pairKey = `${callerRole}->${targetRole}`
+
+      // Back-pressure on instructions: a queued instruction is executed even
+      // after a newer one arrives, so refuse the second one instead of letting
+      // the target burn a turn on an obsolete task.
+      const blocked = kind === '指令' ? pendingInstruction(bus, callerRole, targetRole) : undefined
+      if (blocked && cfg.blockSecondInstruction && args.force !== true) {
+        const at = new Date(blocked.at).toLocaleString('sv-SE')
+        return fail(
+          'instruction_pending',
+          `「${targetRole}」还没回报上一条指令${blocked.ref ? `（${blocked.ref}，${at} 发出）` : `（${at} 发出）`}，` +
+            '很可能仍在执行。再发一条不会替换它，只会排到它后面 —— 目标会先把旧指令跑完。' +
+            '建议：先更新任务/状态文件，等它回报后再下发；确实要插队就加 force: true。',
+        )
+      }
+      const seq = (bus.state.seq.get(pairKey) ?? 0) + 1
 
       let resolved
       try {
@@ -488,7 +603,9 @@ export function apply(ctx, config) {
       if (!resolved || 'error' in resolved) {
         return fail(
           'target_unresolvable',
-          `无法打开目标会话（可能已归档/删除）：${resolved?.error?.message ?? String(resolved?.error ?? 'unknown')}`,
+          `无法打开目标会话（可能已归档/删除，或被 subagent 路由占用）：` +
+            `${resolved?.error?.message ?? String(resolved?.error ?? 'unknown')}。` +
+            '总线目标必须是宿主能直接打开的顶层 GUI 会话；作为子代理（subagent）运行的会话不能作为目标。',
         )
       }
 
@@ -497,7 +614,7 @@ export function apply(ctx, config) {
         return fail('rate_limited', `发送过于频繁，约 ${Math.ceil(slot.retryAfterMs / 1000)} 秒后可再试。`)
       }
 
-      const text = composeBusText({ workspace, fromRole: callerRole, toRole: targetRole, kind, ref, message })
+      const text = composeBusText({ workspace, fromRole: callerRole, toRole: targetRole, kind, ref, message, seq })
       const payload = createUserMessage([{ type: 'text', text }], {
         kind: 'handoff-bus',
         workspace,
@@ -526,11 +643,20 @@ export function apply(ctx, config) {
         targetSessionId: target.sessionId,
         kind,
         ...(ref ? { ref } : {}),
+        ...(kind === '指令' ? { seq } : {}),
         messageId: payload.id,
         woken: wantWake,
         chars: text.length,
       })
 
+      if (kind === '指令') {
+        bus.state.seq.set(pairKey, seq)
+        bus.state.lastInstruction.set(pairKey, { seq, at: sentAt, ...(ref ? { ref } : {}) })
+      } else if (kind === '回报') {
+        // This report answers the reversed pair: worker-a→main acks main→worker-a.
+        bus.state.lastReport.set(`${targetRole}->${callerRole}`, sentAt)
+      }
+
       return {
         ok: true,
         workspace,
@@ -539,6 +665,14 @@ export function apply(ctx, config) {
         messageId: payload.id,
         sentAt,
         woken: wantWake,
+        ...(kind === '指令' ? { seq } : {}),
+        ...(blocked
+          ? {
+              warning:
+                `已强制下发：${targetRole} 上一条指令${blocked.ref ? `（${blocked.ref}）` : ''}尚未回报，` +
+                '它很可能先执行旧版本，再看到这一条。',
+            }
+          : {}),
       }
     },
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-handoff-bus",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Cross-session message bus for DeepSeek Harness GUI conversations: deliver instructions and reports directly between the main conversation and sub-conversations.",
   "type": "module",
   "license": "MIT",