dsh-session-rescue
防止 DeepSeek Harness 冷启动回合卡住：重启或加载会话后，首个回合可能会因令牌计量器同步重放整个会话日志而永久阻塞；此插件会在会话大小达到该危险范围前压缩会话，使重放保持低开销。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:1622352030/dsh-session-rescue#b63803b3ddc1f855e34acc04b06c5b1057f41bd8Session Rescue 以 dsh-session-rescue 发布，当前版本为 0.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Status: v0.2.0 — prevention, not detection. The stall was traced to a specific window and a specific code path (below), and the plugin logic is covered by 55 tests (55 pass / 0 fail). The plugin has been loaded and exercised in an isolated
DSH_HOME, never against the running instance. Be careful reading the mechanism below: the code-level facts are verified, the causal link from the replay to the stall is NOT — there is counter-evidence, stated indocs/DESIGN.md→ Open questions. The stall has not been reproduced under control, and the cold first turn's cost has not been attributed to a specific listener yet.
A DeepSeek Harness plugin that stops the cold-start turn stall: after a restart or a session load, the first turn can block forever with the UI spinning and nothing in the log. This plugin prevents that by compacting the session before its size reaches the zone where the stall becomes fatal.
⚠️ Read this first: the causal claim below was FALSIFIED by direct measurement. The code-level facts in the table are verified, but they are not the cause of the stall.
tools/measure-replay.jsruns the product's ownTokenMeter._syncover a reconstruction of the real session and the entire 526,383-seq cold replay costs 47 ms — against a cold first turn measured at 16,008 ms and turns that never returned. The replay is ~340× too small. The cause is still unknown; what remains true is that cold first turns are far slower than warm ones, it grows with session size, and/compactwas the only observed recovery. Seedocs/DESIGN.md→ Measured falsification.
A stalled session log looks like this, with no error anywhere:
agent/inbox/spliced ← the user message is accepted
turn/start ← the turn is opened
← and then nothing, forever: no step/start, no assistant frames
The silence sits exactly in the preStep window, between turn/start and step/start. The cause is
not a missing timeout and not the network — it is a synchronous full replay of the whole session log
that runs inside that window:
| Step | Evidence |
|---|---|
A restart or session load creates a new Session object | @deepseek-ai/dsh-session/lib/index.js:1322 appends session/end-seed on load |
The token meter's replay state is a WeakMap<Session, state> | @deepseek-ai/dsh-token-meter/lib/index.js:589 |
| A new object ⇒ empty state ⇒ replay from 0 | dsh-token-meter/lib/index.js:679-697, while (state.consumedEvents < session.seq) |
| Something calls it on every pre-step | dsh-compaction-basic/lib/index.js:782 (agent/pre-step) → :862 meter.measure(session) |
So the replay runs between turn/start and step/start | dsh-agent-loop/lib/index.js:528 → :539 → :553 |
That loop is synchronous: it blocks the event loop, so step/start can never be written and
while (await this.turn()) never returns. The UI spins forever.
Measured on one real session (session-db08f763, 5.9 MB, seq space ≈ 517 k):
| Turn | seq at start | cold or warm | preStep duration |
|---|---|---|---|
| 2 | 35,236 | warm (same process) | 231 ms |
| 5 | 45,585 | cold (process just restarted) | 16,008 ms |
| 7 / 28–30 / 34–35 | 93 k / 389 k / 446 k | cold | never returned (user gave up after 20–47 s) |
| 8 / 31 / 36 | same sizes, after /compact | cold | 1.6 s / 10.1 s / 4.7 s ✅ |
Three properties follow from this, all confirmed against the real logs:
/compact does help — it was the only thing that ever recovered these sessions.Honest framing, given the falsification above: the plugin does not absorb the mystery cost.
compactNowbegins withmeasure(), which is cheap (47 ms for the whole session), so compacting at load does not pay whatever the slow listener charges. What the plugin actually delivers is the automation of the one operation observed to restore service — proactive compaction, at load when a session is already large and between turns as it grows. If the slow listener scales with the visible surface, keeping the surface small helps; that is a hypothesis, not a result.
The replay is unavoidable — but where you pay for it is not. Paid inside the user's first turn it is a permanent hang; paid while the agent sits idle after a load it is just a slow start. And once compaction has run, the following cold starts stay cheap.
seq is already past the danger
threshold, compact it before the user's first turn (agent/status → idle). This moves the
unavoidable cost out of the turn and shrinks the surface at the same time./rescue status shows the per-session seq, whether this process has already paid the
replay ("warm") or not ("cold"), and the plugin's own measurement of the preStep window
(turn/start → first step/start) for both cold and warm turns.Only one API is used to act: the official compaction seam,
ctx.compaction.compactNow(agent, signal, commandId)
(@deepseek-ai/dsh-command-compact/lib/index.js:8,54). The service is fetched with ctx.get('compaction')
rather than injected, so the plugin still loads and reports in compositions that have no compaction.
Compaction does not shrink session.seq — the log is append-only and compaction appends its own
records. A plain "compact when seq >= threshold" rule would therefore re-fire on every idle forever.
The trigger is instead "grown by at least minGrowthSeq since the last compaction", and a successful
compaction pushes that baseline to the current seq. Both are property-tested in test/guard.test.js.
busy is also treated specially: it means the core refused the call because a compaction is already
running or the agent is not idle. No replay was paid, so the plugin does not mark that session
warm (otherwise the cold session would miss its GUARD and the next user turn would hang again). Retries
are throttled by a cooldown and a consecutive-busy cap.
- insert:
- id: session-rescue
name: dsh-session-rescue
config:
enabled: true # false = observe and report only, never compact
warnSeq: 40000 # start warning/compacting from here
dangerSeq: 80000 # cold first turn may never return past here
minGrowthSeq: 20000 # compact only after this much growth since the last compaction
cooldownMs: 60000
maxAttemptsPerSession: 6
maxBusyStreak: 5
pollMs: 30000
compactionTimeoutMs: 600000
The default thresholds are calibrated from the table above (40 k is where a cold first turn is
already ~16 s; 80 k is inside the "never returned" range). They are machine- and session-dependent —
measure your own with /rescue status and adjust.
| Path | What it is |
|---|---|
src/host.js | Host plugin entry: session/event + agent/status wiring, GUARD/COMPACT execution, /rescue. |
src/guard.js | Pure decision state machine — when to guard, when to compact, cooldown, caps, busy handling. |
src/size.js | Size metric and thresholds for the danger zone, with the calibration data in comments. |
src/detect.js | Offline only. Stall-signature detector over session events (used by the replay tool). |
src/frames.js | Offline only. Read-only session-log analysis: per-frame zstd decode, synthetic-closer detection. |
bin/dsh-session-rescue.mjs | Read-only scan CLI — usable without installing the plugin. |
tools/replay.js | Replays a real session log through the detector to check hit/miss rates. |
tools/measure-replay.js | Runs the product's own TokenMeter._sync over a reconstruction of a real session log — the measurement that falsified the replay hypothesis (47 ms for 526,383 seqs). |
test/*.test.js | 55 unit and integration tests (node --test), run against a fake cordis context. |
tools/Install-Plugin.ps1 | Idempotent install / rollback for a DSH profile — dry-run by default, snapshot-based. |
docs/DESIGN.md | Design notes: the mechanism with source citations, the fix, bounds and open questions. |
DSH_HOME, not end-to-end against the stall. A real headless Harness run
loaded the plugin, fired its agent/status hook, resolved ctx.get('compaction'), and opened a real
compaction transaction (compaction/start carrying sourceCommandId: "session-rescue-guard-1") —
reproduced twice. The stall itself was not reproduced, and the "compact before the first turn"
ordering is covered by unit tests only. See docs/DESIGN.md → Verification performed.seq is the driver of the loop and is free to
read, so it is used as the proxy — calibrated, not derived.seq does not shrink. The plugin relies on the measured effect, and docs/DESIGN.md
records the question as open./compact
performs. Set enabled: false for report-only mode.signal.throwIfAborted() never gets a chance to run and
cancellation cannot interrupt it.node bin/dsh-session-rescue.mjs scan --stalled-only # sessions that stalled or have an unclosed turn
node bin/dsh-session-rescue.mjs scan --all --json # every workspace bucket, machine readable
It reads session logs (read-only, tail window only, never prints message bodies).
node --test test/size.test.js test/guard.test.js test/host.test.js
node --test test/detect.test.js test/frames.test.js # offline forensics
Developed against DSH Desktop 0.8.2 with @deepseek-ai/dsh@0.1.2-rc.1 — every line reference above
was read from that installed build.
MIT