SessionPersistence.delete: a single-session deletion primitive (proposal with a complete, tested implementation)

[wulun811]

Hi! External contributor here. I implemented a single-session deletion primitive for the persistence seam, with full tests and docs, and would like the team to consider it.

Proposal

SessionPersistence gains abstract delete(id: SessionId): Promise<void> that permanently removes one stored session's durable log, or cancels a created-but-never-appended create intent:

• Unknown ids reject; a live Session or a reserved preparation rejects.
• After deletion the id behaves as unknown for every subsequent operation; create may reuse it.
• Serialized on the per-id write chain with in-flight appends/repairs.
• On success emits session-persistence/deleted (after clearing coordinator state), so derived data can react.

PersistenceBackend gains deleteStored(id) (idempotent no-op for an already-absent artifact). JSONL unlinks the artifact (POSIX fsyncs the parent directory; Windows skips - write-through). SQLite deletes the session row in one BEGIN IMMEDIATE transaction; events cascade via ON DELETE CASCADE.

Full details, alternatives, and consequences are in an Agent Note in the branch: .agents/notes/implemented/architecture/2026-08-21-session-persistence-single-session-deletion.md.

Implementation

Complete and verified on branch: https://github.com/wulun811/deepseek-harness/tree/feat/session-persistence-delete (commit 7f29826970)

• Backend-contract + coordinator + backend-specific tests (new), all green; new-path coverage 100%.
• pnpm run typecheck, pnpm run lint, and the doc gates (translation-pairing, cordis-catalog, scoped-events, doc-budgets, md-wrap, export-jsdoc, package-invariants, readme-limitations) all pass.
• Full unit suite run locally: the 26 failures are all environment-only (git timeouts, missing optional win32-x64 binaries, sandbox CreateProcessAsUser block, pwsh path resolution); one subagent/list-children failure was a parallel-run flake (passes 3/3 in isolation). None relate to this change.

Why it matters

The persistence seam is append-only with no deletion primitive; pruning stored sessions is out-of-band backend maintenance, and nothing notifies derived data when a stored id becomes unusable. A deletion primitive is the foundation for session management: retention policies, GC, and recursive subtree deletion can build on it.

I understand the repo does not currently accept external pull requests - happy to adapt to whatever review or integration process you prefer. Thanks for considering it.

[somebear]

+1 from a downstream consumer. We are building a single-user localhost product on top of DSH's public plugin seams, and user-managed Session deletion is a hard privacy requirement for our v0.1 release — we deliberately do not work around its absence with private imports or direct file removal, so this seam is currently our only remaining release blocker.

The contract proposed here maps exactly onto what we need: reject live Sessions, idempotent absent results, consistent cleanup of backend-owned derived state, and a session-persistence/deleted event that derived data can react to. If it helps move this forward, we would be glad to validate the branch against our plugin compatibility suite as a real external consumer and report back.

Is there any signal from the maintainers on whether a deletion primitive like this could be integrated? Even a rough sense of direction would help us plan whether to keep waiting or to descope deletion from our v0.1 privacy acceptance. Thanks to @wulun811 for the thorough proposal.

[fuweiliang988-hub]

We validated the exact DSH 0.1.2-alpha.3 ACP distribution as a downstream single-user localhost product. Private stdio, multi-session close/list/resume, crash recovery, semantic turns, cancellation, one-shot permission rejection, MCP admission rollback, secret containment and a hash-bound profile/tool manifest all pass. The only remaining M1 gate is formal Engine Session deletion: ACP does not advertise session/delete, the wire returns -32601, and a closed Session remains listable/resumable after restart. We deliberately do not remove private files; an independent real probe confirms the late-drain/index resurrection risk described in #4411.

The SessionPersistence.delete foundation proposed here is directionally right. For our acceptance it would need a current alpha.3 port plus an ACP-owned quiescent delete surface, idempotent repeat behavior, derived index/projection and unreferenced attachment cleanup, and end-to-end list-invisible / resume-fails / restart-non-resurrection tests. We can validate an updated branch against our packaged-runtime compatibility suite and report exact evidence. Would the maintainers prefer this Discussion to remain the coordination point, and is the persistence seam proposed here still the intended foundation?

[wulun811]

Thanks @somebear and @fuweiliang988-hub — glad this is getting exercised on real setups, and the checklist is the right pressure for a durable-delete seam.

Quick status: the branch is now rebased onto alpha.4 and folds in the derived-state eviction that was open on the rc.8 cut. (Upstream removed the SQLite backend since my first cut, so the seam ships JSONL-only; the backend hook is shared.)

On the checklist:

• alpha.4 port — done; branch link below.
• Derived indices/projections — same change: SessionProjectionCache and WorkspaceRegistry subscribe to session-persistence/deleted and evict their own durable rows (checkpoint row; header/path indices, archive set, workspace membership). The "delete under a running session and the index re-adds it" resurrection class from [Bug/Feature] sessionPersistence: no delete/forget API — externally removed session files leave stale in-memory index entries that get resurrected on disk #4411 closes at the persistence boundary via the same event.
• Idempotence + unknown ids — repeat delete rejects as not-found; a live Session or reserved preparation rejects; contract-tested across backends.
• list/resume/restart visibility — after delete the id behaves as unknown: excluded from list(), load/readFrom reject, a fresh mount over the same root never names it (restart probe test), and create may reuse it.
• Attachments — deliberately out: they live in a content-addressed pool (~/.dsh/attachments/…), not owned per-session, so orphan reclamation is a separate GC change rather than a hidden side effect of delete.
• ACP — consumer-side follow-up; the event is in place to subscribe to, but ACP wiring is not part of the seam.

Evidence: 505 unit tests across the touched packages pass, including both eviction paths and their fail-soft branches.

Branch: https://github.com/wulun811/deepseek-harness/tree/feat/session-persistence-delete
(PR creation is disabled in this repo — happy to open a PR if that changes.)

@jl0nd0n0 your rc.2 implementation landed on the same contract independently — worth comparing designs so downstream effort concentrates once. If maintainers have a different deletion design in mind, we'd rather align than invent.