dsh-handoff-bus 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,161 @@
 # Changelog
 
+## 0.3.0 — 2026-10-19
+
+The previous release made short conversations possible; this one makes them
+**automatic**. Three things that a person had to remember are now enforced by the
+plugin, and all three attack the same number: how many tokens a conversation
+carries into every single request.
+
+### Added — start-up briefing
+
+Before a conversation's first request, the plugin appends one short message that
+tells it which handoff files to read and how:
+
+- `briefingFiles` (default `README.md`, `PROTOCOL.md`) are read in full;
+- `briefingScan` globs are read as **structure + tail** — `grep -n '^## '` for the
+  headings, then `tail -n briefingTailLines` for the newest entries;
+- everything else is located by heading and read with `sed -n 'A,Bp'`.
+
+Reading a 95 KB ledger in full costs ~30k tokens on the very first request; this
+costs ~200 and is announced once per conversation (`briefing: false` disables it).
+Only fires when the workspace actually has a handoff directory.
+
+### Added — context budget
+
+Each conversation's prompt is measured before it is sent (ASCII ≈ 3.8 chars per
+token, CJK ≈ 1.6, plus `contextOverheadTokens` for the system prompt and tool
+definitions). At `contextWarnRatio` (default 0.4) the conversation is told:
+
+- finish the current task, start nothing new;
+- write the state — including unanswered instruction refs and artefact paths —
+  into the handoff directory;
+- tell the user the context is too full and a new conversation should take over,
+  then stop.
+
+At `contextStopRatio` (default 0.7) the wording becomes an instruction to stop
+after the current step. Both are ordinary user messages appended to the same
+request: **no extra turn, no extra model call.** Each level is announced once and
+re-armed if a compaction brings the estimate back down.
+
+`contextWindowTokens` defaults to 524288 rather than the declared 1048576,
+because real overflow happens well before the declared window. Set it to your
+provider's real window if you know it.
+
+### Added — handover before leaving
+
+`bus_unregister` now refuses to unbind a conversation when the handoff directory
+has not been written for `handoverWindowMin` (default 30) minutes, returning
+`handover_missing`. Leaving is the moment a conversation's context dies; the files
+are all the next shift inherits. `force: true` overrides, and the result reports
+how fresh the handoff is.
+
+### Added — budget visible in tool results
+
+`bus_register` / `bus_whoami` / `bus_list` / `bus_send` carry a `context` block
+(`pct`, `tokens`, `level`), and `bus_send` also reports `targetContext`. Sending an
+instruction to a conversation that is already at 60% now returns a warning telling
+you to archive it instead of piling more work onto a stale context.
+
+### Fixed
+
+- "Unanswered instruction" was decided by comparing ISO timestamps with `>=`.
+  Several deliveries inside one turn share a millisecond, so a report could be
+  treated as acknowledging an instruction that came **after** it, silently
+  clearing the pending state (and with it the back-pressure and the takeover
+  warning). The delivery log now carries a monotonic `order`, replayed from the
+  file, so restarts keep the correct answer. Existing `deliveries.jsonl` files
+  replay correctly without migration.
+
+## 0.2.0 — 2026-10-19
+
+Shorter conversations are the only lever that actually lowers cost: a conversation
+sitting at 400k tokens pays that much again on every request, and one at 20k pays
+one twentieth. This release makes "one temporary conversation per task" cheap to
+run and hard to forget.
+
+### Added — three-level roles
+
+- `bus_register(parent="rgb")` allocates the next free child (`rgb.1`, `rgb.2`, …).
+  Nobody has to remember or pre-plan numbers.
+- Registering a dotted role materialises its parent as a **virtual node** (a name
+  with no session attached), so lines never need a separate registration step.
+- `bus_send(target="rgb")` routes to the most recently active live conversation
+  under that line and reports `routedFrom` / `routedTo`. Naming `rgb.2` explicitly
+  still wins. At most `routeMaxAttempts` (3) candidates are probed.
+- `bus_register(replaces="rgb.2")` hands a line over: the old conversation is
+  retired, and the result warns when it still had an unanswered instruction (read
+  the ledger, do not redo the work from scratch).
+- New tool `bus_unregister` lets a finished conversation leave the table, so the
+  line routes to a fresh one. Refused while an instruction is still awaiting a
+  report; `force: true` overrides.
+- `bus_list` now returns the tree with `parent` / `depth` / `children` / `virtual`
+  / `awaiting` / `msgCount` / `idleMin` / `routeTo` / `suggestHandoff`.
+- `bindings.json` upgrades from v1 to v2 on read; existing files keep working.
+
+### Added — `done` is required on every 指令
+
+`bus_send(kind="指令")` without `done` returns `instruction_incomplete`. An
+instruction that does not say what "finished" means invites a second instruction,
+and a second instruction is a whole extra turn of the target's context — the most
+expensive way to say six words. `done` is echoed in the delivered message, so the
+report can be checked against it. Disable with `requireDone: false`.
+
+### Added — report digest and `urgent`
+
+A plain `回报` is now injected into the target's history **without waking it**, and
+the target is woken once when `digestMinCount` reports (default 3) or
+`digestMaxWaitSec` (default 900s) have accumulated. The digest message lists the
+reports and says the full text is already above it.
+
+- `urgent: true` wakes immediately (stuck / failed / decision needed).
+- `kind="请求"` is urgent by default.
+- An urgent message folds the queued backlog into the same wake-up instead of
+  waking twice.
+- `wake: true` / `wake: false` still override everything explicitly.
+- The only timer in the plugin exists while reports are queued, and is `unref`'d.
+  Reports are already in the target's history, so a restart loses the wake-up, not
+  the message.
+
+### Changed
+
+- Instruction sequence and back-pressure are counted per **actual** target, so
+  `target="rgb"` and `target="rgb.2"` cannot be used to sneak a second instruction
+  past the guard.
+- `bus_list` no longer lists a role twice after a session re-registers.
+- Documentation rewritten around the three-level model.
+
+## 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

@@ -6,30 +6,38 @@ A small host plugin for [DeepSeek Harness](https://www.deepseek.com/harness/) (D
 
 ## What it does
 
-- ✅ Main → sub: `bus_send(target="worker-a", kind="指令", ...)`
-- ✅ Sub → main: `bus_send(target="main", kind="回报", ...)`
-- ✅ Addresses conversations by role name; the target is woken (`wake: true` by default)
+- ✅ Main → line: `bus_send(target="rgb", kind="指令", done="…", ...)` — write only the line name and it lands on whichever conversation under that line is alive
+- ✅ Line → main: `bus_send(target="main", kind="回报", ...)`
+- ✅ Three levels: `main` / line `rgb` / temporary conversations `rgb.1`, `rgb.2`; replacing a conversation never changes what the main conversation writes
 - ✅ Scoped by session cwd: each workspace gets its own independent bus
+- ✅ Remembers three things for you: a start-up briefing in every new conversation, a context-watermark notice at 40%, and a refusal to unregister without writing the ledger
 
 ## What it does not do
 
-- ❌ No file watching, no timers, no autonomous work when you are away
+- ❌ **It does not create conversations.** You open them in the GUI; the plugin only registers and routes.
+- ❌ **It does not close conversations.** It gives you the signal (`suggestHandoff`); closing is your call.
+- ❌ **It does not compress context.** Compaction is triggered by the host; the plugin can neither read the water level nor change the threshold.
+- ❌ No file watching, no polling, 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
 
 ```
-you ──open the main conversation──▶ main (bus_register main)
-                                      │
-                                      │ 1. write task files / instruction files
-                                      │ 2. bus_send(target="worker-a", kind="指令", ref="D-001", message="…")
-                                      ▼
-                                   worker-a sub-conversation (bus_register worker-a)  ← woken
-                                      │ 3. do the work, write the report file
-                                      │ 4. bus_send(target="main", kind="回报", ref="R-…")
-                                      ▼
-                                   main ← woken, reads the report, decides the next step
+you ──open the main conversation──▶ main (bus_register role="main")
+                                     │
+                                     │ 1. write task files / instruction files
+                                     │ 2. bus_send(target="rgb", kind="指令", done="…", message="…")
+                                     ▼
+                                  rgb line ──▶ rgb.1 (bus_register parent="rgb")  ← woken
+                                     │ 3. do the work, write the report file
+                                     │ 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
+                                     ▼
+                                  rgb.2 (bus_register parent="rgb" replaces="rgb.1")
 ```
 
 Keep the bus message short: summary + file pointers. The authoritative content stays in your files.
@@ -37,9 +45,11 @@ Keep the bus message short: summary + file pointers. The authoritative content s
 ## Requirements
 
 - A DSH **web/desktop** profile with the Host session controller and session store. Headless/SDK-only profiles may not provide them; the plugin then stays inactive (it declares `inject`).
-- Tested on DSH `0.2.0-rc.x` (desktop, Windows). Host services such as `sessionController.resolveAgent`, `agent.followup/inject`, `sessions.flush`, and `session.header.cwd` are internal APIs, not a public contract; a future DSH release may require a patch.
+- 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.
-- v0.1 keeps tool result messages and relayed message bodies in Chinese; error codes are stable English identifiers. Role names are free-form (the examples use Chinese line names).
+- 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.
+- **No session creation or closing**: both are GUI-only actions.
 
 ## Install
 
@@ -68,19 +78,197 @@ dsh plugin --profile <profile> add dsh-handoff-bus
 ## Quick start
 
 1. Main conversation: `bus_register(role="main")`
-2. Each sub-conversation: `bus_register(role="worker-a")` (any role name)
-3. `bus_list` shows the role table of the current workspace
-4. Main → sub: `bus_send(target="worker-a", kind="指令", ref="D-001", message="…")`
-5. Sub → main: `bus_send(target="main", kind="回报", ref="R-001", message="…")`
+2. Each sub-conversation: `bus_register(parent="rgb")` → gets `rgb.1`
+3. `bus_list` shows the role tree and where each line would route
+4. Main → line: `bus_send(target="rgb", kind="指令", done="…", message="…")`
+5. Line → main: `bus_send(target="main", kind="回报", ref="R-001", message="…")`
 
-Role names are arbitrary strings you choose; `worker-a` / `worker-b` are only examples.
+Role names are lowercase letters, digits, dots, underscores and hyphens, at most three levels (`main` / `rgb` / `rgb.1` / `rgb.1.worker`).
+
+`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="…")` |
+| Main gives work to a line | `bus_send(target="rgb", kind="指令", done="pytest tests/test_rgb.py passes", message="…")` |
 | Sub reports back | `bus_send(target="main", kind="回报", ref="R-…", message="…")` |
-| 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` |
+| Stuck, main must act now | same, plus `urgent: true` |
+| Main asks for status (no work) | `bus_send(target="rgb", kind="请求", ref="Q-…", message="Status only, do not start work.")` |
+| Queue without waking | add `wake: false` |
+
+## Three-level roles
+
+| Level | Examples | Who maintains it | Rotate? |
+|---|---|---|---|
+| 1 main | `main` | Registered once by you in the main conversation | No. There is exactly one per bus |
+| 2 line | `rgb`, `world`, `scene`, `reward` | Appears automatically as a *virtual node* the first time a child registers under it | **No.** It is only a name; no session is attached |
+| 3 temporary conversation | `rgb.1`, `rgb.2` | Numbered by the plugin when a new conversation registers | **Yes**: one task per conversation, unregister when done, open a new one next time |
+
+### Registering
+
+```
+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)
+```
+
+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`.
+
+### 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")`.
+
+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.
+
+### Handing a line over
+
+```
+bus_register(parent="rgb", replaces="rgb.1")
+```
+
+The old conversation moves to `retired` (kept for `retiredRetentionDays`, default 7, so a "why can't I send here" question has an answer). If it still had an unanswered instruction, the result names that `ref` and tells the new conversation to **read the ledger first instead of redoing the work from scratch**.
+
+### When to archive a temporary conversation
+
+All three at once:
+
+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` 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.
+
+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.
+
+## Instructions must carry an acceptance test
+
+`bus_send(kind="指令")` without `done` is refused (`instruction_incomplete`):
+
+```
+bus_send(target="rgb", kind="指令",
+         message="Wire the RGB camera calibration into the data loader",
+         done="calibration file is read; all three cameras align on the same frame id; pytest tests/test_rgb.py passes")
+```
+
+`done` is echoed in the delivered message so the report can be checked against it. This removes the most common waste: an instruction without an acceptance test makes the sub guess, a wrong guess produces a follow-up instruction, and every follow-up costs the target a whole context reload.
+
+Disable with `requireDone: false`.
+
+## Report digest and `urgent`
+
+Not every report deserves a wake-up — the main conversation usually holds the longest context, so its wake-ups are the most expensive.
+
+| Case | Default |
+|---|---|
+| `kind="回报"` without `urgent` | **No wake.** The message goes into the main conversation's history; after `digestMinCount` reports (default 3) or `digestMaxWaitSec` (default 900s), one summary message wakes it once |
+| `kind="回报"` + `urgent: true` | Wakes immediately |
+| `kind="请求"` | Urgent by default (a request is a decision ask) |
+| `wake: true` / `wake: false` | Explicit override, highest priority |
+
+Only three things deserve `urgent`: **stuck**, **failed and needs a new approach**, **needs a decision**. "Done", "50%", "here is the artifact path" do not.
+
+An urgent message folds any queued backlog into the same wake-up (the text says "N earlier reports are already queued") instead of waking twice. Urgent deliveries still obey the rate limits.
+
+Implementation note: a batched report is **injected into the history without waking**, so a client restart loses the wake-up, never the message. The single timer exists only while a digest is pending and is `unref`'d.
+
+Disable with `digestReports: false` (back to waking on every report).
+
+## 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.
+- **Numbering follows the actual target**, so `target="rgb"` and `target="rgb.2"` landing
+  on the same conversation share one sequence and cannot be used to bypass the guard.
+
+A sub-conversation prompt that makes this reliable:
+
+```text
+收到 [BUS 指令] 后，先调用 bus_list 看 latest 里「main->自己角色」的 seq。
+如果消息末尾写的「本线第 N 条」小于 seq，说明已被后面的指令取代：
+只做最新那条，不要重复劳动，并在回报里说明跳过了哪一条。
+```
+
+## Context budget and start-up briefing
+
+The longer a conversation lives, the more every request costs. The three things
+below are what a person would otherwise have to remember; the plugin enforces them.
+
+| When | What happens | Default |
+|---|---|---|
+| Before a conversation's first request | A **briefing** is injected: which handoff files to read, and how to read the big ones | `briefing: true` |
+| Context crosses the watermark | A **budget** notice: finish the current task, write the ledger, tell the user to switch conversations | 40% warn / 70% stop |
+| Unregistering a role | Refused when the handoff directory has not been written lately (`handover_missing`) | 30 minutes |
+
+All three **append one user message to the request that was going to happen
+anyway** — no extra turn, no extra model call. Each costs 100–200 tokens and saves
+the tens of thousands that reading a 95 KB ledger in full would cost on the very
+first request.
+
+A briefing looks like this (only when `briefingFiles` / `briefingScan` match real
+files):
+
+```text
+[BUS 开工简报] 本工作区有 _HANDOFF/ 协作目录：D:\project\_HANDOFF
+开工顺序（先读完再动手；大文件不要整篇读）：
+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 会被拒。
+```
+
+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.
+
+`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.
+
+## Token cost
+
+The bus itself is cheap; the turns it triggers are not.
+
+| Item | Cost |
+|---|---|
+| Tool schemas (5 tools) | ~1400 tokens per request, in every conversation, used or not |
+| Message wrapper | ~120 tokens per delivered message (header, workspace, time, protocol lines) plus a few dozen for `done` |
+| **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.
+
+Since 0.3.0 the plugin remembers items 1 and 3 for you (briefing, budget notice,
+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.
+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.
+5. **`wake: false`** for anything that is not a "start working now" signal.
+6. **Use `kind="通知"` for state sync**: it lands on disk and costs nothing.
+7. **Never poll.** A main conversation calling `bus_list` every few minutes re-reads the most expensive context and learns nothing.
+8. **Pointers, not payloads.** Summary + file path in the body; the report stays in the file.
+9. **Disable the plugin in profiles that never use it** — that removes the ~1400-token schema.
 
 ## New workspace setup (copy-paste prompt)
 
@@ -109,22 +297,23 @@ Step 2 — register first, then verify:
   bus_list
 
 Step 3 — to dispatch, write the task/instruction file first, then call:
-  bus_send(target="worker-a", kind="指令", ref="D-001",
+  bus_send(target="rgb", kind="指令", ref="D-001",
+           done="report-a.md is written and pytest tests/test_rgb.py passes",
            message="Task file task-a.md is updated. Read it and D-001; when done write report-a.md and bus_send back to main.")
 
 Step 4 — sub-conversations only write their own status/report files;
 handoff/.bus/ is the bus state (bindings.json / deliveries.jsonl) — do not edit it.
 
-Create the files, register main, then show me the role table with bus_list.
+Create the files, register main, then show me the role tree with bus_list.
 ```
 
-Sub-conversation prompt:
+Sub-conversation prompt (send this at the start of every new conversation on a line):
 
 ```text
-Read <this directory>/handoff/task-a.md and start.
-First call bus_register(role="worker-a").
-Only write status-a.md and report-a.md; when done call
-bus_send(target="main", kind="回报", ref="R-<date>-01", message="Report written to report-a.md; conclusion: …; next: …")
+You are a new conversation on the rgb line. First call bus_register(parent="rgb") to get your number,
+then read handoff/rgb/STATE.md for progress. Only write your own status/report files under handoff/rgb/.
+When done call bus_send(target="main", kind="回报", ref="R-<date>-01", message="Report written; conclusion: …; next: …").
+Add urgent: true when stuck, failed, or you need a decision.
 ```
 
 ## Multiple workspaces
@@ -140,13 +329,21 @@ bus_send(target="main", kind="回报", ref="R-<date>-01", message="Report writte
 
 | Tool | Purpose |
 |---|---|
-| `bus_register(role, note?)` | Register this conversation as a role **in its workspace** |
+| `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_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()` | 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` |
 
 `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_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.
+
+Wake policy when `wake` is omitted: `指令` / `通知` wake immediately; `回报` goes to the digest without waking; `请求` wakes immediately. An explicit `wake` always wins.
+
 ## Configuration
 
 Configuration is read in this order (later wins):
@@ -163,7 +360,29 @@ Example `config.json`:
   "stateDirName": ".bus",
   "maxMessageChars": 4000,
   "maxSendsPerHour": 30,
-  "maxPairSendsPer10Min": 8
+  "maxPairSendsPer10Min": 8,
+  "blockSecondInstruction": true,
+  "pendingInstructionTtlSec": 600,
+  "requireDone": true,
+  "routeMaxAttempts": 3,
+  "retiredRetentionDays": 7,
+  "digestReports": true,
+  "digestMinCount": 3,
+  "digestMaxWaitSec": 900,
+  "handoffAfterMessages": 40,
+  "handoffAfterIdleMin": 30,
+  "briefing": true,
+  "briefingFiles": ["README.md", "PROTOCOL.md"],
+  "briefingScan": [],
+  "briefingScanLimit": 4,
+  "briefingTailLines": 80,
+  "contextBudget": true,
+  "contextWindowTokens": 524288,
+  "contextWarnRatio": 0.4,
+  "contextStopRatio": 0.7,
+  "contextOverheadTokens": 40000,
+  "requireHandoverOnLeave": true,
+  "handoverWindowMin": 30
 }
 ```
 
@@ -177,6 +396,28 @@ 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 |
+| `digestReports` | `true` | Batch plain reports (disable to wake on every report) |
+| `digestMinCount` | 3 | Reports per digest wake-up |
+| `digestMaxWaitSec` | 900 | Longest a report waits before the digest fires |
+| `handoffAfterMessages` | 40 | `suggestHandoff` threshold: messages exchanged |
+| `handoffAfterIdleMin` | 30 | `suggestHandoff` threshold: minutes idle |
+| `briefing` | `true` | Inject the start-up briefing before the first request of a conversation |
+| `briefingFiles` | `["README.md","PROTOCOL.md"]` | Files to read in full, relative to the coordination directory |
+| `briefingScan` | `[]` | Globs read as structure + tail, e.g. `["4*-*.md"]` |
+| `briefingScanLimit` | 4 | How many matching ledgers to name (newest first) |
+| `briefingTailLines` | 80 | Lines in the `tail -n` suggested by the briefing |
+| `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 |
+| `contextOverheadTokens` | 40000 | Fixed cost of the system prompt and tool definitions |
+| `requireHandoverOnLeave` | `true` | Refuse `bus_unregister` when the coordination directory is stale |
+| `handoverWindowMin` | 30 | Window for the check above, in minutes |
 
 `deliveries.jsonl` is append-only. Delete it manually if it grows; automatic rotation is planned for a later release.
 
@@ -188,10 +429,15 @@ Example `config.json`:
 | `no_workspace` | The conversation has no cwd |
 | `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 does not exist in this workspace |
+| `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 |
+| `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) |
+| `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_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 |
 | `delivery_failed` | Delivery error |
 | `aborted` | The tool call was cancelled |