dsh-branch-inbox-guard
English | 中文
Keeps a DSH fork child from inheriting its parent's queued prompts. Branch a session, type a question,
and the branch runs your question — not the prompt the parent had queued next.
- Pure host plugin: no core-file patching, no client half, no configuration.
- Durable: the drop is appended as a normal
agent/inbox/spliced cancel event, so the queue stays clean across restarts.
- Idempotent, and conservative — it only removes items it can prove came from the fork parent.
The problem it removes
A DSH branch session is a fork child: its log is seeded with the parent's completed-turn prefix.
That prefix can contain the parent's undelivered agent/inbox/spliced events — prompts you queued while
the parent was still working.
On DSH 0.1.5 the agent inbox is a session projection that folds the whole log, so those replayed
splices become the child's pending queue. The prompt you then type in the branch is appended behind
them, and the branch's first turn claims the parent's queued prompt instead — the question you typed
appears to vanish.
On DSH 0.1.1-rc.2 the inbox was rebuilt from the log suffix after the fork cut, so the same seed
produced an empty queue. This plugin restores that behaviour through public APIs, without patching
core packages.
parent session branch session (fork child)
turn 10 ─ completed seed = parent prefix
queue: [A] [B] ← undelivered queue: [A] [B] ← replayed from the seed on 0.1.5
turn 11 runs A you type C → queue: [A] [B] [C]
first turn runs A ← C waits, and looks lost
with this plugin: queue [C] → first turn runs C
What it does
On every agent/created it inspects the pending queue and drops exactly the items whose inserting
agent/inbox/spliced event lies inside the session's inherited prefix (seq < session.inheritedEventCount):
| Pending item | Action |
|---|
| Inserted before the fork cut (the parent's) | Dropped. A single inbox.clear() when the whole queue is inherited, otherwise one inbox.remove(id) per item — both recorded durably as cancels. |
| Inserted by the session's own events | Kept. A branch that already queued its own prompts (or a session resumed later) only loses the inherited ones. |
Unseeded session (inheritedEventCount is 0) | Never touched. |
| Origin not traceable in the log | Kept (conservative). |
It also covers fork-context subagents (their seed has the same property, so a delegated task would
otherwise queue behind the parent's prompts), and it heals sessions that were polluted before you
installed it: open such a branch once and the phantom items are cancelled, while the prompt you typed
in it survives.
Install
# from npm (prebuilt — skips the build-approval step)
dsh plugin --profile web add dsh-branch-inbox-guard
# from GitHub
dsh plugin --profile web add github:xine2009cn/dsh-branch-inbox-guard
# from the release tarball
dsh plugin --profile web add https://github.com/xine2009cn/dsh-branch-inbox-guard/releases/latest/download/dsh-branch-inbox-guard-0.1.0.tgz
# from a local file / directory
dsh plugin --profile web add ./dsh-branch-inbox-guard-0.1.0.tgz
Then restart DSH (docker restart <container>, or restart the app) and reload the Web GUI. The plugin
is a host-side bundle row, so a profile whose dsh.profile.bundles lists it will load it at boot.
Verify it is working
Every time it drops something, the DSH log shows one line:
[branch-inbox-guard] session-xxxxxxxx: dropped 5 inherited prompt(s) from its fork parent
End-to-end check: queue a message in a session while the agent is running, branch from a completed
turn, then look at the new branch — its queue should be empty, and a question typed there should start
running immediately.
Uninstall
dsh plugin --profile web remove dsh-branch-inbox-guard
docker restart <container>
Nothing else is left behind: the plugin writes no files outside its own package, and never modifies
session history — the only thing it appends is the cancel event that removes the inherited items.
Compatibility
Verified against DSH 0.1.5-rc.1 and 0.1.5-rc.2 (the versions whose inbox projection folds the
fork-inherited prefix). On 0.1.1-rc.2 the queue is already empty at fork time, so the plugin is a
no-op there.
It uses only documented faces: the agent/created event, agent.inbox (nextTurn, nextStep,
clear, remove), session.inheritedEventCount, session.snapshotEvents() and session.id.
If a future DSH release makes the inbox projection skip the inherited prefix again (i.e. fixes this
upstream), this plugin simply finds nothing to drop — and can be uninstalled.
Tests
npm test # or: node test/guard.test.mjs
Self-contained unit tests (no dependencies, no fixtures, no session data): mixed queue keeps the own
prompt and drops the inherited ones, a pure fork child gets a single durable clear(), inherited
steering input (next-step) is dropped, an unseeded session is untouched, an empty queue appends
nothing, a second run is a no-op, and an item with no traceable origin is kept.
License
MIT
