dsh-wait-guard

dsh-wait-guard

A completion gate for DeepSeek Harness agents: as long as any subagent an Agent dispatched is still running, that Agent's turn is not allowed to end.

It is a pure Host-only plugin — no tools registered, no settings written, no files touched, no global state. Remove the bundle and everything is exactly as it was.

中文说明

---

Install

Straight from GitHub (no npm account needed; verified in an isolated profile):

# track main
dsh plugin --profile <your-profile> add github:dn4hjtcr9s-del/dsh-wait-guard

# pin a version (reproducible)
dsh plugin --profile <your-profile> add github:dn4hjtcr9s-del/dsh-wait-guard#v0.1.0

From npm, once published — shorter:

dsh plugin --profile <your-profile> add dsh-wait-guard

Or, in the Web UI: Plugins → Add plugin → paste whatever follows add above. Installing a bundle activates through HMR; replacing an already-installed package needs a restart to load a fresh module generation.

Uninstall: remove the bundle from the same page, or dsh plugin --profile <your-profile> remove dsh-wait-guard.

---

What it guarantees

Delivery is never gated by this plugin: messages are spliced into the Agent inbox by the runtime. A subagent messaging a different agent does not pass through here at all.

---

Configuration

The bundle's cordis.patch.yml inserts one row; configuration lives on that row.

Example override (in a profile patch, a bundle patch, or your own workspace bundle):

- id: wait-guard
  config:
    firstWaitMs: 120000
    nudge: false

A row patch replaces config wholesale — restate every field you still want.

---

How it works

The gate hangs off agent/turn-stopping, the event dsh-agent-loop awaits immediately before it re-reads the inbox and decides whether to close the turn:

// dsh-agent-loop: the two checks around the awaited event
if (turnEnds && this.inbox.nextStep.length === 0) {
    await this.dispatch.serial("agent/turn-stopping", { turn, signal });  // ← the gate pauses here
}
if (turnEnds && this.inbox.nextStep.length === 0) break;                  // ← the turn really ends

The dispatch is awaited and serial, its return value is discarded, and turnEnds is not writable from a listener — so the only lever a listener has is the inbox. This plugin simply does not return while work is pending, and then releases; anything it injected keeps the turn alive for one more step.

Inside that await it polls the whole descendant tree (listDescendants, filtered by the Agent registry's real status), and exits on: an arrival, the silence timer, a quiet subtree, cancellation (signal.aborted), or plugin disposal. Pending waits are resolved on disposal, so unloading the plugin can never leave a turn stuck.

---

Verification

npm test        # or: node test/self-test.mjs

22 tests drive the real plugin against a fake host context: no pending work, single-level and multi-level (idle coordinator with a running grandchild) holds, arrival deactivates and injects nothing, deactivation is temporary, opt-in companion, opt-in batching, wall-clock nudge timing under slow probes, one notice per stop attempt, nudge:false silence, abort, disposal, fail-open/fail-closed probes, session-format-V4 source admission for every emitted notice, conditional policy section, config fallbacks, and message-id/summary bounds.

Every live behaviour above was also reproduced against a real Harness profile: the gate held a premature answer for 11–61 seconds until the last subagent settled, and the recorded turn/end count stayed at zero throughout.

---

Development notes

• Host-only bundle: no dependencies, no build step, no client entry — the implementation is a single import-free module, so nothing resolves at load time.
• Editing the code while the app runs: configuration hot-reloads, but module files do not (dsh-hmr ships with root: []), and the loader reuses the runtime already imported for a row id. Either restart, or add a never-imported entry file plus a new row id and bump the query on its internal import. Do not put a query string in a row's name: the loader treats it as a filesystem path and the import silently fails.
• Tested against DSH 0.1.7-rc.2 (macOS desktop) and 0.1.5-rc.2 (npm CLI).

Known limits

1. A subagent that never settles means the Agent waits. Reasons to exit: the timer notice gives the model a chance to interrupt_agent, the user can stop the turn, or set nudge: false for a silent gate.
2. Each arrival costs one model request (that is the price of "handle the message now"). Set releaseOn: ['user','agent-message'] to batch settlements instead.
3. The gate never rewrites the reason a turn ended — it only postpones the decision.
4. Non-continuable one-shot subagents are not covered: they cannot be resumed and never send settlement notices, so they are invisible to the listing this plugin watches.

License

MIT