[Bug/Feature] sessionPersistence: no delete/forget API — externally removed session files leave stale in-memory index entries that get resurrected on disk

[123123liang]

[Bug/Feature] sessionPersistence: no delete/forget API — externally removed session files leave stale in-memory index entries that get resurrected on disk

Reported: 2026-08-24 ｜ Reporter: DSH user (binfengqiliang)

Environment

• dsh 0.1.1-rc.2 (web profile, Windows, Node v24.18.0)

Symptom

When session files are removed outside the host's session API (there is no delete surface today), the running server's in-memory session index keeps the entry:

1. Re-creating a session with the same id fails with session "<id>" already exists in this backend — even though the session directory was deleted and verify_session reports the session no longer exists.
2. On the next session event (e.g. a new import), the server rewrites session_projcache.json / workspace.json from its in-memory state, resurrecting entries that were manually cleaned on disk. Disk-level cleanup is therefore ineffective while the server is running.

Impact

• Broken "retract → re-import/replace" workflows for plugins that manage imported sessions (no way to drop a stale entry without a server restart).
• Ghost sessions remain visible in the web GUI (empty/broken) until restart.
• External tooling that cleans up session artifacts cannot synchronize with the running server's index.

Expected

• A session forget/delete API (even if the underlying file is not removed, at least evict the in-memory + persisted index entry), or
• createIfAbsent / the session registry tolerating stale index entries whose backing file is missing (auto-evict or auto-replace), or
• The index being rebuilt/validated against the sessions directory instead of blindly persisting memory.

Repro

1. Import a session via any path (e.g. a chat-import plugin).
2. Delete its ~/.dsh/sessions/<workspace>/<sessionId>/ directory and remove its session_projcache.json / workspace.json entries while the server is running.
3. Attempt to create a session with the same id → already exists in this backend.
4. Trigger any session event (new import) → the cleaned entries are rewritten back to disk.

Context

Discovered while recovering a lost import in the dsh-chat-import plugin flow (see companion reports). The plugin's retract_import explicitly documents "DSH 无 delete 面" (no delete surface), which is the root gap this issue asks to close.

[jl0nd0n0]

Root-cause confirmation from an independent implementation (+ one deeper layer: detached drain resurrection)

@123123liang - I hit this exact gap independently while building durable chat deletion (delete active/archived chats: persisted log, subagent descendants, workspace/projection references) on top of 0.1.1-rc.2 sources. Your report matches what I observed, and I can confirm both layers of the problem:

1. No delete surface (your point): there is no remove/forget anywhere on the persistence seam, so external cleanup always desynchronizes the running index.
2. A second resurrection path you did not need to hit: even after removing the stored artifact, AgentHandle.dispose() resolves before the coordinator's detached retirement drain flushes buffered batches. A late-drained seed rewrites session.jsonl.zstd after deletion - so any future remove() must settle against storage (e.g., delete -> poll listSnapshots() until absent, bounded retry) rather than trusting dispose ordering alone.

What a complete surface needs, mapping to your "Expected" section:

• SessionPersistence.removeStored? hook implemented per backend (JSONL dir rm; SQLite DELETE FROM sessions with event cascade)
• PersistenceCoordinator.remove(id) serialized per id, refusing live sessions, dropping states/preparations after retirement
• Workspace registry eviction (entities + archive set)
• A gateway RPC that validates root + subagent-descendant sets (session-busy / session-in-use / session-not-found), disposes handles, then removes storage and broadcasts host/session-removed
• Projection-cache forget() so checkpoints cannot seed an unrelated future fold

Verified working end-to-end against a source-booted server: archived and active chats deleted, stored logs physically gone from disk (absence confirmed via listSnapshots), removal frames observed over WebSocket, and the error codes above preserved.

One scoping note for anyone considering the plugin route: this cannot be a plugin today - it requires new methods on the abstract persistence class and each backend, compile-time wire schema extensions, and workspace-UI changes. It has to land in core.

I keep this as a maintained feature branch on a fork (rebased periodically); happy to share the diff privately if the team ever wants to evaluate it.