dsh-session-deleter
Delete what the harness gives no API for deleting: a whole stored Session — and
a Session's contents — from the DSH web UI. Deletion is a move to a private
recycle bin; bytes leave the disk only on an explicit, separately confirmed
permanent delete.
Release history: CHANGELOG.md.
Why this exists
@deepseek-ai/dsh-session-persistence-jsonl offers create/open/flush/
stat/list and nothing else, so the UI can archive a Session but never remove
one. The sidebar keeps its row until the next Workspace write prunes the id, the
subagent/catalog is append-only so a child cannot be dropped by appending, and
no client-side service exposes a delete. This plugin adds the missing operation
without touching the harness.
What it does
Three operations, reachable from the UI:
- Delete a whole Session — moves the Session's entire directory (every log
generation) into the recycle bin. Reversible.
- Restore — moves a held directory back to its original path. It refuses to
overwrite an occupied path rather than guessing.
- Delete permanently — the only irreversible step, and the only one that
reclaims disk space. Requires a second, explicit click (or
confirm: true).
Where it appears in the UI
| Surface | Slot | Position |
|---|
| Sidebar foot, beside Settings | sidebar.footer.action | order: 20 — always visible, no hover needed |
| Session picker dialog | shell.overlay | opened by the footer entry |
| A Session's "..." menu | sidebar.workspaces.session.menu.item | order: 500, after the shipped pin/rename/fork/archive rows |
| Confirmation dialog | shell.overlay | frame-wide floating layer |
| Management page | settings.section | order: 50 in Settings |
| Management page (same body) | shell.overlay | order: 5 — the in-plugin manage overlay, see below |
The sidebar-foot entry is the primary door and it does not depend on hover:
DSH only draws a Session row's "..." trigger while the pointer is over a
non-current row, so a reader who never hovers sees no sign the plugin exists.
The picker it opens lists every deletable session itself, and a running or
current session is shown but not deletable.
The management page renders in two places from one component. The shell owns the
Settings panel and exposes no client service that opens it: layout.selectPanel(id)
only addresses a main panel registered in the sidebar.panellist slot (whose
shipped occupants are plugins and dsh-market), and selecting an unregistered
key throws. So the in-plugin entries that promise "manage" — the picker's
「管理回收站」 and the dialog's 「打开管理页」 — open the manage overlay, which
renders the same body. A best-effort selectPanel("settings") is still attempted
first, purely as a courtesy for a build where that key does exist.
Both dialogs are dry runs first: the plan shows the directory, the size, the log
generations, what else is affected, and what residue stays behind — before
anything moves.
Design commitments
Reversible by default. A first request never removes bytes. rename into
the recycle bin is atomic on one filesystem and is the whole of the destructive
work.
Nothing the backend cannot read afterwards. Rewrites re-emit one checksummed
Zstandard frame per durable batch. The .jsonl.zstd artifact is a
concatenation of independently decodable frames, not one stream — so a single
recompressed stream would decode to the right bytes yet stop matching the
backend's structural scanner on the next append.
Multi-generation aware. Session directories legitimately hold a v3 log, a
v4 log, or both. Nothing here hardcodes a filename.
Refuses what it cannot safely do. A running Session's log is open for
writing, so it is refused rather than deleted under its writer. The Session
issuing the request cannot delete itself. A Session id is a path segment, so
traversal-shaped ids are rejected before reaching the filesystem.
Host routes
Served on the harness web server under /session-deleter:
| Method | Path | Purpose |
|---|
| GET | /health | Roots in effect and the current Session id |
| GET | /inventory | Every stored Session, with bytes, generations, titles |
| GET | /plan?sessionId=… | Dry run: consequences, residue, blockers |
| POST | /delete | {sessionId, force?} → move into the recycle bin |
| GET | /trash | Held entries, orphan detection, size |
| POST | /restore | {id} → move back |
| POST | /purge | {id, confirm: true} → remove bytes |
| GET | /ledger?limit= | Append-only operation log |
| GET | /messages?sessionId=… | Surface messages with live/shadowed status |
| POST | /messages/shadow | {sessionId, seq} → tombstone one message (line A) |
| POST | /messages/unshadow | {sessionId, tombstoneSeq} → undo one shadow |
| POST | /messages/truncate | {sessionId, throughSeq} → drop the tail (line B) |
| POST | /messages/untruncate | {sessionId, backupPath} → restore the backup |
Shadow vs truncate: what each one really does
- Shadow is append-only and fully reversible. A
developer/message
tombstone replaces one surface node in the model-visible fold — the same
mechanism the shipped compaction flow uses. The transcript keeps showing
the original row (by the surface's own documented contract), and the
tombstone derives to no LLM message. Deleting a message from the model's
context is what this does; deleting it from the screen requires
truncation.
- Truncate removes events from the artifact by rebuilding it from the
surviving frame-aligned prefix. It takes the transcript rows with it and
keeps a
.bak- backup for a byte-exact restore. It is the only message
operation that touches existing bytes.
Configuration
Optional, supplied as the bundle row's config:
- insert:
- id: session-deleter
name: 'dsh-session-deleter'
config:
sessionRoot: 'D:/somewhere/sessions'
trashRoot: 'D:/somewhere/trash'
protectCurrentSession: true
refuseLiveSessions: true
Defaults: sessionRoot = <DSH_HOME|~/.dsh>/sessions, trashRoot =
<home>/session-trash/sessions.
State on disk
<home>/session-trash/sessions/ — held directories, one per deletion, plus
manifest.json.<home>/session-trash/ledger.jsonl — one append-only line per operation
phase. A torn trailing line (a crash mid-append) is dropped on read rather
than treated as corruption.
Verification
Each check runs real filesystem and HTTP work against a sandbox copy of a real
session tree — no mocks of the plugin's own logic.
node tools/verify-host.mjs "$DSH_HOME/sessions"
node tools/verify-http.mjs
node tools/verify-client.mjs
node tools/check-locale.mjs # static: t() keys vs both dictionaries
node tools/verify-frames.mjs <log> [<log> …]
node tools/verify-manage.mjs # needs a browser + the gate cookie, see below
node tools/verify-ui.mjs # same
node tools/verify-footer.mjs # same
verify-host covers inventory/title parsing, the full hold → restore → purge
cycle, refusal paths (occupied path, purged entry, unknown entry), atomic
replacement backups, ledger durability, byte-exact frame round trips, and
traversal-shaped id rejection. verify-http mounts the plugin through a
webServer stub matching the shipped contract and drives all eight routes over
real HTTP. verify-client executes the browser bundle in a VM against a stub
module loader and asserts every slot registration. check-locale proves every
t("…") call resolves in both dictionaries (a missing key renders as the literal
key text) and that no key is shadowed by a duplicate. verify-manage,
verify-ui, and verify-footer drive the real GUI in Chrome and prove the
surfaces render, not merely register: verify-manage opens the picker from the
sidebar foot, clicks 「管理回收站」, and asserts the management view's rendered
counts equal what the routes return — an empty-but-mounted panel cannot pass.
Nothing machine-specific is committed. tools/harness.mjs discovers the browser
and puppeteer-core at run time, so the suites work on another machine; each
value has an override:
| Variable | Purpose |
|---|
DSH_URL | GUI origin under test (default http://127.0.0.1:3080) |
DSH_COOKIE_NAME / DSH_COOKIE_VALUE | The GUI gate cookie; overrides in-memory minting in the browser suites |
DSH_HOME | Harness home whose credential file the cookie is minted from |
DSH_CHROME | Chrome/Chromium binary |
DSH_PUPPETEER_CORE | puppeteer-core entry module |
DSH_SHOTS_DIR | Where screenshots land |
DSH_SESSIONS_DIR | Source tree verify-http copies its fixture sessions from |
DSH_LAUNCHER / DSH_PLUGIN_DIR | Used by tools/restart-and-verify.ps1 |
The gate cookie is a bearer credential and is never written to this repository.
When DSH_COOKIE_NAME/DSH_COOKIE_VALUE are absent, cookieForBaseUrl() in
tools/harness.mjs mints one in memory from this Harness home's own
.credentials.yaml (client-connection/browser-session), signing it exactly as
dsh-client-connection does — payload {version, authority, issuedAt, expiresAt}
in milliseconds, HMAC-SHA256 over the base64url body with the decoded 32-byte
secret, and the name dsh-auth-<base64url sha256(authority)>. Nothing is printed
or persisted. The environment variables still win when set, so a run against a
remote host needs no local credential file.
Uninstalling
Remove the bundle row and the package. Held directories stay in the recycle bin
and can be restored by hand — the manifest records each entry's original path.
