dsh-handoff-bus 0.1.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,296 @@
 # 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
+**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