dsh-handoff-bus 0.3.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,171 @@
 # Changelog
 
+## 0.4.2 — 2026-10-19
+
+### Fixed — tool results and the retire decision read the same number
+
+`contextReport` (behind `bus_register` / `bus_whoami` / `bus_list` / `bus_send`)
+counted characters and added the 40,000-token constant, while retirement and
+drain were decided from the host's real projection. A fresh conversation
+therefore read `7.6%` (40000 / 524288) while the plugin could already be treating
+it as 20%, 78% or worse. Showing a second, disagreeing number is worse than
+showing none: the human plans around the figure on screen.
+
+`contextReport` is now async and goes through `measureSession` — the same probe,
+same 60-second cache, same `min(declared window, contextWindowTokens)` divisor —
+and derives `level` from `contextTier`, so the reported tier is the tier that
+actually retires the session. The character estimate survives only when the host
+offers nothing to measure, and then the result carries `estimated: true`.
+
+`context.tokens` is only meaningful with a projection; when only the compaction
+count can be read, `tokens`/`pct` are reported as 0 with `estimated: true`, and
+the `bus_send` overflow warning uses a phrase that refuses to print "0%".
+
+## 0.4.1 — 2026-10-19
+
+Four defects found by running 0.4.0 for real. Three of them had nothing to do
+with the queue logic and everything to do with what the text told the model.
+
+### Fixed — an instruction no longer tells the target to leave
+
+`composeBusText` appended 「任务做完就 bus_unregister，不用等人提醒」 to every
+instruction. Models followed it literally: a conversation that reported at
+12:45:13 was retired at 12:45:14, twice in a row, one second later. The line went
+empty, so the next instruction needed a brand-new conversation and a cold
+context — the exact cost the bus exists to avoid.
+
+The rule now says the opposite: **report, then stand by**. Retire only when the
+context is full or the user says the work is over. `bus_unregister`'s own
+description was rewritten for the same reason.
+
+### Fixed — `handoff/` is created, and existing state is migrated
+
+Nothing ever created the directory. Reports landed in the workspace root as
+`.txt`, and `stateDirFor` quietly fell back to `~/.dsh/handoff-bus/<slug>/`
+where nobody would look for them. Worse, the first person to create the folder
+by hand would have silently orphaned every binding.
+
+Registration now creates it, and when a central state directory already exists
+it is copied in before the bus is resolved, so counters and bindings survive.
+Every prompt that names a file now names `handoff/<role>.md`.
+
+### Fixed — `role: "a"` no longer turns a line into a conversation
+
+`bus_register` accepted a bare line name as `role`, and its parameter text
+actively suggested it. Binding the line itself makes routing short-circuit to
+that session, so the numbered substitutes never receive anything.
+
+A bare line name passed as `role` is now coerced to `parent` and reported as
+`coercedFrom`, so the wrong parameter cannot produce the wrong topology.
+
+### Added — 「注册 a」 is defined, once, for a fresh conversation
+
+An unregistered conversation is told the three-level shape and the three steps:
+`bus_register(parent="a")` → read `handoff/a/` → report. The number is allocated
+by the plugin, so nobody has to remember which one is next.
+
+It also states where the newcomer stands: `a.6` behind an idle `a.3` is a
+**substitute**, and tells it to stand by. Stated only — the queue order is
+untouched.
+
+The hint is deliberately independent of the start-up briefing, which stays silent
+until the folder has files — precisely the state a fresh workspace is in.
+
+## 0.4.0 — 2026-10-19
+
+0.3.0 gave every conversation a budget and a briefing. 0.4.0 makes the bus
+**hold the queue itself**: numbering, routing, back-pressure and retirement all
+move from "the model remembers to do it" to "the bus refuses otherwise".
+
+### Changed — routing is a queue, not a popularity contest
+
+`bus_send(target="rgb")` used to pick the most recently active conversation,
+which meant a pre-registered `rgb.2` and `rgb.3` (activity 0) could never be
+chosen. It now picks the **lowest number** among candidates that are not retired
+and hold no unfinished instruction. Pre-registered conversations become what they
+always were meant to be: a bench, not a race.
+
+### Changed — child numbers are monotonic and never reused
+
+`rgb.1` archived means the next one is `rgb.4`, never `rgb.1` again. The
+high-water mark is persisted in `bindings.counters` because the `retired` archive
+is pruned after `retiredRetentionDays` (7) — a counter that lived there would
+recycle numbers after a week, silently moving an old instruction's meaning onto a
+different conversation. v1/v2 files derive the counter from their existing roles.
+
+### Changed — back-pressure has no time escape
+
+`pendingInstructionTtlSec` (600s) freed the line automatically, so a long task
+was never protected. Removed: a line owns **one** instruction until it reports.
+`force` is gone from `bus_send` too — it was the same escape under another name.
+A dead conversation releases the line by leaving the role table, not by waiting.
+
+### Added — `line_busy` and `no_available_session`
+
+Two distinct refusals instead of one vague one: `line_busy` means the line has
+live conversations but all are working; `no_available_session` means everyone is
+retired, or there is nobody at all.
+
+### Added — `preempt` (the only way to take a busy line)
+
+`preempt: true` on a 指令 delivers via `inject` into the running turn (no new
+turn), forces the body to open with "stop the current task, save the half-done
+work, then switch", and **cancels** the instruction it displaced. A late report
+for the cancelled ref is recorded but never counts as an acknowledgement — a
+stale task finishing must not free the line for the task that replaced it.
+
+### Added — retirement on measured context
+
+Compaction count and water level are read from the host for **any** session
+(`sessionQuery.observeSession` for `compaction/end`, the projection cache for
+`contextWindow` and the live sums) instead of being estimated from the current
+message list.
+
+| | advise | stop |
+|---|---|---|
+| compactions | ≥ 1 | ≥ 2 |
+| water level | > 50% | > 70% |
+
+**Compaction count wins outright.** Once a conversation has been compacted, the
+percentage it reports afterwards is meaningless — compaction is what resets it.
+So ≥ 2 compactions stops a conversation whatever the level says, and 1 compaction
+only advises even at 78%.
+
+Retirement only marks: `retired: true`, `retiredReason: "context_full"`, and the
+level/compaction snapshot at that moment. The session, its context and its place
+in the tree all stay. **A conversation is only retired when it is idle** — on its
+own report, or when routing finds it free — so a task is never cut in half.
+
+The bus does not tell the user "rgb.1 should be archived": it drops that sentence
+into `rgb.1`'s own history (`inject`, no wake) and lets the child say it to its own
+window, with the number to ask for next.
+
+### Added — the main conversation drains instead of stopping
+
+A main conversation at **≥ 2 compactions or > 85%** (wider than a child, because
+stopping it stops the whole workspace) enters *drain*: it stops issuing
+instructions and keeps receiving reports. Nothing interrupts the lines — they
+finish at their own pace. A sweep (900s, backing off to 3600s after 3 quiet
+rounds) watches for every line to go idle; only then is the user told to archive
+and open a new main. No hard stop: a draining conversation being compacted costs
+nothing, because all it needs to remember is "wait".
+
+New error codes `draining` and `self_retired`. A new conversation calling
+`bus_register(role="main")` takes the binding over and resets the state; child
+bindings and numbers are untouched.
+
+### Added — departure reminder on every instruction
+
+Every 指令 ends with "任务做完就 bus_unregister，不用等人提醒" — one line, so the
+next shift does not depend on the user saying "收工".
+
+### Config
+
+Removed: `blockSecondInstruction`, `pendingInstructionTtlSec`.
+Added: `childWarnRatio`, `childStopRatio`, `mainWarnRatio`, `mainDrainRatio`,
+`compactionWarn`, `compactionStop`, `contextProbeSec`, `drainSweepSec`,
+`drainSweepIdleRounds`, `drainSweepBackoffSec`.
+
 ## 0.3.0 — 2026-10-19
 
 The previous release made short conversations possible; this one makes them

package/README.md

@@ -35,9 +35,10 @@ you ──open the main conversation──▶ main (bus_register role="main")
                                      │ 4. bus_send(target="main", kind="回报", ref="R-…")
                                      ▼
                                   main (woken once per few reports)
-                                     │ 5. this task is done: unregister rgb.1, open rgb.2 for the next one
+                                     │ 5. rgb.1 stays and waits; only when its context is full
+                                     │    (or the user is done) does it unregister, and rgb.2 takes over
                                      ▼
-                                  rgb.2 (bus_register parent="rgb" replaces="rgb.1")
+                                  rgb.2 (bus_register parent="rgb")
 ```
 
 Keep the bus message short: summary + file pointers. The authoritative content stays in your files.
@@ -48,7 +49,7 @@ Keep the bus message short: summary + file pointers. The authoritative content s
 - Tested on DSH `0.2.0-rc.x` (desktop, Windows). Host services such as `sessionController.resolveAgent`, `agent.followup/inject`, `sessions.flush`, `session.header.cwd`, the `agent/created` event and the `agent/pre-step` hook are internal APIs, not a public contract; a future DSH release may require a patch. If the hook throws, the plugin degrades to "no advisory" and the turn proceeds untouched.
 - No npm dependencies. The plugin imports only Node builtins.
 - Tool result messages and relayed message bodies are in Chinese; error codes are stable English identifiers. Role names are lowercase ASCII with dots (`main`, `rgb`, `rgb.1`).
-- **No context-length reading**: the plugin does not touch the host's projection API, so `bus_list` reports bus activity (message count, idle minutes), not token water level. Use dsh-context's `/context` for the real number.
+- **Context water level comes from the host**: `sessionQuery.observeSession` counts compactions from the event log, `sessionProjectionCache.cachedSnapshot` reads the `contextTimeline` bucket sums and window. Both are internal services; when they are unavailable the plugin falls back to a character estimate and flags it `estimated: true`. `bus_list.contextPct` only appears for conversations that have been measured.
 - **No session creation or closing**: both are GUI-only actions.
 
 ## Install
@@ -109,22 +110,44 @@ Role names are lowercase letters, digits, dots, underscores and hyphens, at most
 bus_register(parent="rgb")                        → role: "rgb.1"
 bus_register(parent="rgb", note="calibration")    → role: "rgb.2"
 bus_register(role="main")                         → the main line
-bus_register(role="rgb")                          → one conversation owns the line itself (optional)
+bus_register(role="rgb")                          → same as parent="rgb": you get rgb.N (see below)
 ```
 
 All you say in each new sub-conversation:
 
-> Take work on the rgb line: call `bus_register(parent="rgb")` first, then read `handoff/rgb/STATE.md`.
+> 注册 rgb
+
+The plugin sends that conversation a fixed three-step note on its first request
+(`bus_register(parent="rgb")` → read `handoff/rgb/` → report), so the model never
+needs to know which number is next, nor guess between `role` and `parent`.
+
+**A line name never becomes a conversation.** `role="rgb"` used to bind the line
+itself, after which routing short-circuited to it and the numbered conversations
+never received anything. A bare line name passed as `role` is now coerced to
+`parent`, and the result says so via `coercedFrom`.
+
+Registration also tells you where you stand: if a smaller-numbered conversation
+is already on the line, you are a **substitute** and should stand by. That is
+stated, not enforced — the queue order is untouched, the lowest number always
+wins.
 
 ### How a target is resolved
 
 1. `target="rgb.2"` → that exact conversation, no guessing.
-2. `target="rgb"` → inside the `rgb` subtree, sorted by most recent traffic, each candidate is opened in turn and **the first one that opens wins** (at most `routeMaxAttempts`, default 3).
-3. None opens → `no_live_session`, with the hint to open a fresh conversation and `bus_register(parent="rgb")`.
+2. `target="rgb"` → the line **queue**: candidates are the conversations that are
+   not retired and hold no unfinished instruction, sorted by number, and the
+   **lowest number wins**. Each is opened in turn until one resolves (at most
+   `routeMaxAttempts`, default 3).
+3. Nobody usable → `line_busy` (there are conversations, all working) or
+   `no_available_session` (all retired, or the line is empty).
 
 The result carries `routedFrom` / `routedTo`, so nothing is a black box. `bus_list.routeTo` tells you where it would land before you send.
 
-> **Keep one live conversation per line.** Most-recently-active is not "best suited": if `rgb.2` is busy with task A and you send B to `rgb`, it lands on `rgb.2` behind A. Unregister the old conversation when its task is done, then open a new one — then `target="rgb"` is never ambiguous.
+> **A line owns one instruction at a time.** A bench is not a parallel pool: while
+> `rgb.1` owes a 回报, `rgb.2` does not sneak in — the send is refused, and naming
+> `rgb.2` explicitly does not help either. There is no `force`; the only override
+> is `preempt: true`, which injects "stop and save, then switch" into the running
+> turn and cancels the displaced instruction.
 
 ### Handing a line over
 
@@ -136,13 +159,43 @@ The old conversation moves to `retired` (kept for `retiredRetentionDays`, defaul
 
 ### When to archive a temporary conversation
 
-All three at once:
+The bus now decides this from **measured** context (compaction count first, water
+level second) and marks the conversation `retired` when it is idle:
+
+| | advise | stop taking work |
+|---|---|---|
+| compactions | ≥ 1 | ≥ 2 |
+| water level | > 50% | > 70% |
+
+A retired conversation keeps its context and its place in the tree; routing simply
+skips it. The bus does not lecture the user from the outside — it drops one line
+into the retired conversation's own history, and that conversation tells its own
+window: *"archive me, the next one will be `rgb.4`"*.
 
-1. `bus_list` shows `awaiting: false` (no unanswered instruction);
-2. the current task is reported and has no follow-up;
-3. `suggestHandoff: true` (default: 40 messages exchanged, or 30 minutes idle).
+`suggestHandoff` still exists as a softer hint (40 messages, or 30 minutes idle)
+for conversations that are merely stale rather than full. `bus_list` also exposes
+`compactions` and `contextPct` once a conversation has been measured.
 
-`suggestHandoff` is a **heuristic, not a context gauge**. `msgCount` only counts bus messages; the context a conversation accumulates by reading files and running commands is invisible to the bus — use dsh-context's `/context` for the real number.
+### When the main conversation has to go
+
+The main conversation fills up too, but its line is wider: **≥ 2 compactions or
+> 85%**. Stopping it stops the whole workspace, so the cost is not the same as
+swapping a temporary conversation.
+
+It is never cut short. It **drains**:
+
+- it stops issuing instructions (`draining` is returned) and keeps receiving reports;
+- no line is interrupted — they finish at their own pace;
+- a background sweep checks every 900s whether every line is idle, backing off to
+  1 hour after 3 quiet rounds, because a long task does not deserve to be poked;
+- the moment everything is idle, it says: write the ledger, archive me, open a new
+  main and say "take main".
+
+A new main calling `bus_register(role="main")` takes the name over; child bindings
+and numbers are untouched, and their reports land on the new main automatically.
+
+Being compacted while draining is harmless — at that point it only has to remember
+one word: wait.
 
 Rule of thumb: one tool call adds roughly 2–3k tokens, so 150–200 tool calls lands around 400k. **A line is ready to hand off after 8–10 turns**, before it starts forgetting things.
 
@@ -186,9 +239,12 @@ Every delivery is a separate turn in the target conversation. If `main` sends th
 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.
+- **A second `指令` is refused** while the line still owes a `回报` (`line_busy`).
+  Update the task file, wait for the report, then dispatch again. There is no
+  `force` and no timeout: a long task keeps the line. To take the line anyway,
+  `preempt: true` — it injects into the running turn, orders "stop and save the
+  half-done work", and cancels what it displaced. A late report for the cancelled
+  `ref` is recorded but never frees the line.
 - **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.
@@ -230,13 +286,21 @@ files):
 1. 全文读：_HANDOFF/README.md、_HANDOFF/01-铁律.md
 2. 只读结构与末尾：_HANDOFF/41-回报-B线.md —— 先 grep -n '^## ' 看标题，再 tail -n 80 看最新回执；
 3. 要细节再按标题定位：sed -n 'A,Bp' 文件；不要 cat 整篇，也不要把大段日志贴进对话。
-收工规矩：把状态写回 _HANDOFF/（含未回报的指令 ref 与产物路径），否则 bus_unregister 会被拒。
+状态规矩：写回 _HANDOFF/<你的角色>.md（.md，不是 .txt；含未回报的指令 ref 与产物路径）。不收工不要注销，做完回报后待命即可。
 ```
 
 The estimate is derived from the prompt text (ASCII ≈ 3.8 chars/token, CJK ≈ 1.6)
 plus `contextOverheadTokens` for the system prompt and tool definitions. It is an
 estimate within roughly 15%, not the host's exact number.
 
+**The estimate is only the fallback.** For a registered conversation, the `context`
+in a tool result is the same measurement the retirement decision uses (the host's
+projection buckets plus the compaction count); only when the host cannot be probed
+does it fall back to the character estimate, flagged `estimated: true`. Two
+different numbers would be worse than one imprecise number: `bus_list` once read
+7.6% (the 40,000 constant over an empty message list) while the plugin was already
+treating the same session as 78%.
+
 `contextWindowTokens` defaults to 524288, not the declared 1048576: in practice
 `context overflow` starts around 430k, so 40% of the declared window would fire
 after it is already too late.
@@ -260,7 +324,7 @@ handover gate); nobody has to watch it.
 
 Ways to spend less, best first:
 
-1. **Shorten conversation life** (biggest win): one task per conversation, `bus_unregister` when done, open a fresh one for the next task. Going from 400k to 20k makes the same work an order of magnitude cheaper.
+1. **Never run one line to the end** (biggest win): hand it off when it reaches the retirement line, before it starts forgetting and re-reading the same file. **But leaving right after a task is pure waste** — report, then stand by; the next instruction reuses the same warm context. Leaving early means the next instruction needs a brand-new conversation with a cold history.
 2. **Stop pasting logs into the conversation**: write them to a file, grep the hits, paste only those lines.
 3. **Make `done` specific** — it removes the "one more thing" follow-up that costs a whole context reload.
 4. **Reserve `urgent` for stuck/failed/decision** — everything else rides the digest.
@@ -323,21 +387,24 @@ Add urgent: true when stuck, failed, or you need a decision.
 - State location:
   - workspace has `handoff/` → `<workspace>/handoff/.bus/`
   - otherwise → `<DSH_HOME>/handoff-bus/<sanitized-workspace>/`
+  - The first `bus_register` creates `handoff/`, migrating an existing central
+    state into it first, so the move never orphans bindings or counters.
 - Cross-workspace addressing is not implemented. Open an issue if you need it.
 
 ## Tools
 
 | Tool | Purpose |
 |---|---|
-| `bus_register(role?, parent?, replaces?, note?)` | Register this conversation. `parent` alone allocates the next free child; `replaces` takes a line over from an older conversation |
-| `bus_unregister(role?, force?)` | Leave the table when the task is done, so the line routes to a fresh conversation. Refused while an instruction is unanswered |
+| `bus_register(role?, parent?, replaces?, note?)` | Register this conversation. `parent` alone allocates the next free child; a bare line name in `role` is coerced to `parent` (`coercedFrom`). Result carries `queue` standing |
+| `bus_unregister(role?, force?)` | Leave the table **only when archiving (context full) or the user says the work is over** — not after each task. Refused while an instruction is unanswered |
 | `bus_whoami()` | Current role + workspace |
 | `bus_list()` | Role tree (`parent` / `depth` / `children` / `virtual`) with signals (`awaiting` / `msgCount` / `idleMin` / `routeTo` / `suggestHandoff`) plus `latest` |
-| `bus_send(target, message, kind?, done?, ref?, urgent?, wake?, force?)` | Deliver to a role or a line; a line name routes automatically and the result carries `routedFrom` / `routedTo` |
+| `bus_send(target, message, kind?, done?, ref?, urgent?, wake?, preempt?)` | Deliver to a role or a line; a line name queues to the lowest-numbered usable conversation and the result carries `routedFrom` / `routedTo` |
 
 `kind`: `指令` (instruction), `回报` (report), `通知` (notice), `请求` (request). These four values are literal tokens — keep them in Chinese; do not translate them.
 
-Every result except `bus_unregister` carries `context` (estimated `pct` / `tokens` / `level`);
+`bus_whoami` / `bus_list` / `bus_send` carry `context` (measured `pct` / `tokens` / `level` /
+`compactions`; `estimated: true` when the host could not be probed);
 `bus_register` / `bus_whoami` / `bus_list` also carry `handoff` (directory, entry files, minutes
 since the last write); `bus_send` adds `targetContext` and warns when the target is already past
 the watermark — archive it instead of piling on more work.
@@ -361,8 +428,6 @@ Example `config.json`:
   "maxMessageChars": 4000,
   "maxSendsPerHour": 30,
   "maxPairSendsPer10Min": 8,
-  "blockSecondInstruction": true,
-  "pendingInstructionTtlSec": 600,
   "requireDone": true,
   "routeMaxAttempts": 3,
   "retiredRetentionDays": 7,
@@ -381,6 +446,16 @@ Example `config.json`:
   "contextWarnRatio": 0.4,
   "contextStopRatio": 0.7,
   "contextOverheadTokens": 40000,
+  "childWarnRatio": 0.5,
+  "childStopRatio": 0.7,
+  "mainWarnRatio": 0.5,
+  "mainDrainRatio": 0.85,
+  "compactionWarn": 1,
+  "compactionStop": 2,
+  "contextProbeSec": 60,
+  "drainSweepSec": 900,
+  "drainSweepIdleRounds": 3,
+  "drainSweepBackoffSec": 3600,
   "requireHandoverOnLeave": true,
   "handoverWindowMin": 30
 }
@@ -396,8 +471,6 @@ 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 |
 | `requireDone` | `true` | `kind="指令"` must carry `done` |
 | `routeMaxAttempts` | 3 | Candidates probed when `target` is a line name |
 | `retiredRetentionDays` | 7 | How long retired roles are remembered |
@@ -414,8 +487,15 @@ Example `config.json`:
 | `contextBudget` | `true` | Context watermark notices |
 | `contextWindowTokens` | 524288 | What counts as 100% (not the declared 1048576) |
 | `contextWarnRatio` | 0.4 | Warn: finish the current task, write the ledger, switch conversations |
-| `contextStopRatio` | 0.7 | Demand an immediate wrap-up |
+| `contextStopRatio` | 0.7 | Generic watermark for conversations that are not registered on the bus |
 | `contextOverheadTokens` | 40000 | Fixed cost of the system prompt and tool definitions |
+| `childWarnRatio` / `childStopRatio` | 0.5 / 0.7 | Water level at which a line conversation is advised / retired |
+| `mainWarnRatio` / `mainDrainRatio` | 0.5 / 0.85 | Water level at which the main conversation is advised / starts draining |
+| `compactionWarn` / `compactionStop` | 1 / 2 | Compaction count that advises / retires (outranks the level) |
+| `contextProbeSec` | 60 | How long a measured context is reused |
+| `drainSweepSec` | 900 | Idle check interval while the main conversation drains |
+| `drainSweepIdleRounds` | 3 | Quiet rounds before backing off |
+| `drainSweepBackoffSec` | 3600 | Backed-off interval |
 | `requireHandoverOnLeave` | `true` | Refuse `bus_unregister` when the coordination directory is stale |
 | `handoverWindowMin` | 30 | Window for the check above, in minutes |
 
@@ -430,12 +510,15 @@ Example `config.json`:
 | `invalid_role` / `invalid_target` / `invalid_message` / `invalid_kind` | Invalid argument |
 | `caller_not_registered` | This conversation has no role yet |
 | `target_not_registered` | The target role or line does not exist in this workspace |
-| `no_live_session` | The line has no live conversation left; open one and register it |
+| `line_busy` | A conversation on this line still owes a `回报`; wait, or `preempt: true` |
+| `no_available_session` | Every conversation on the line is retired (context full), or the line is empty |
+| `draining` | This main conversation is winding down: reports only, no new instructions |
+| `self_retired` | This conversation is retired (context full): write the ledger, ask the user to archive it |
 | `role_not_found` / `role_virtual` / `not_owner` | `bus_unregister`: no such role / it is a virtual line node / it belongs to another conversation |
 | `self_target` | The target is this conversation |
 | `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` |
+| `instruction_pending` | `bus_unregister` only: an instruction to this role is still unanswered |
 | `instruction_incomplete` | `kind="指令"` is missing `done` |
 | `handover_missing` | The coordination directory was not written before leaving; write the state, or pass `force: true` |
 | `flush_failed` | Queued but persistence was not acknowledged |