dsh-session-pruner

DSH session lifecycle management plugin — full-type session lifecycle management: one-shot subagents archived on completion, continuable subagents and main sessions archived when idle, a capacity cap, and projection-cache cleanup. Prevents session-library accumulation stalls at the source.

Every session type has a defined destination: finished one-shot subagents are archived automatically, idle continuable subagents / main sessions are archived, and overflow is recycled by priority. Archive first (recoverable), delete after expiry — the GUI syncs within 30s, fully panel-configured with hot reload.

简体中文 · Apache-2.0 · npm

Why

DSH (DeepSeek Harness) caches a full projection of every session in session_projcache.json (token stats, context pressure, ...), and the storage backend rewrites the whole file atomically on every write. When the session library accumulates thousands of subagent sessions:

• The cache balloons past 100MB and each checkpoint fully re-serializes → main process CPU 250%+
• The single-threaded event loop is saturated → every session load stalls, even GET / times out

Managing session lifecycle (this plugin) is the root fix: no session accumulation → no cache rows → no stalls.

Features: full-type lifecycle

Session type	Trigger	Action	Default
one-shot subagent	log contains session/end-seed (finished)	archive/delete at next scan	30min interval
continuable subagent	idle over N days	archive (recoverable)	off (0 days)
main session	idle over N days	archive (recoverable)	off (0 days)
any type	total exceeds capacity cap	recycle by one-shot → continuable → main + oldest	400
archive directory	kept over N hours	physically deleted	24 hours

Archive mechanism (recoverable)

Cleaned sessions are moved to ~/.dsh/sessions-archive/ first (workspace/session-id structure preserved) — they disappear from the GUI immediately (the list only reads the sessions directory), but the files remain and can be restored manually:

# Restore: mv back into the sessions directory
mv ~/.dsh/sessions-archive/<workspace>/<session-id> ~/.dsh/sessions/<workspace>/

A "delete directly" mode (no archive, irreversible) is also available.

Safety (double protection)

• Running sessions are never touched: logs without session/end-seed are never cleaned (checked in both the one-shot path and the capacity cap)
• live protection: sessions still held in the in-memory session store (open/loading) are skipped
• Main sessions do not participate in capacity recycling by default (configurable)
• Per-action failure isolation: every action is try/catch wrapped

How it works

scan (scheduled, default 30min)
  ├─ pruneArchive: physically delete expired archive sessions
  ├─ iterate ~/.dsh/sessions/*/ decompress log (system zstd, multi-frame)
  │     ├─ origin: main | subagent       (session header)
  │     ├─ mode: one-shot | continuable  (subagent/descriptor event)
  │     └─ ended: contains session/end-seed
  ├─ one-shot + ended ──→ archive (archiveMode)
  ├─ continuable/main idle N days ──→ archive
  ├─ total > cap ──→ recycle by priority + oldest (skip running/live)
  └─ each archive also: purge projcache row + workspace accounting

…