better-dsh-session-deletetool 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,299 @@
+# Changelog
+
+## 0.4.0
+
+**The package is `better-dsh-session-deletetool` now.** Every name that pointed at the old identity was
+renamed in one pass, so nothing resolves the old spelling any more:
+
+- the npm package name, the GitHub repository (`Lzcdebear/better-dsh-session-deletetool`), and the
+  `repository` / `homepage` / `bugs` URLs plus every install target in the READMEs;
+- the four Host routes: `/better-dsh-session-deletetool/inspect`, `/delete`, `/catalog` and
+  `/delete-batch`;
+- the client module id, the locale namespace, the sidebar menu row, both `shell.overlay` seats and the
+  bulk anchor's registration ids, the `data-dsh-plugin` marker, and the React display name;
+- the Host loader row in `cordis.patch.yml` — both the row `id` and the module `name` the profile
+  imports;
+- the Host's `[better-dsh-session-deletetool]` log prefix and its effect labels.
+
+**The family view is written down now.** The dialogs have drawn a conversation's subagents and derived
+conversations as one tree for several releases, but neither README said so out loud. Both now open that
+section by saying that the sidebar cannot show the relation and the dialog is the one place it is
+drawn, and the npm description says it too.
+
+A profile that had the old name linked has to link the new one: the bundle key in
+`dsh.profile.bundles` and the dependency key in the profile's own `package.json` both change.
+
+## 0.3.9
+
+**Both dialogs now draw the same family tree.** The single conversation's dialog and the bulk one share
+one renderer: a row per Session, and under every row a collapsible **子智能体 (n)** block followed by
+a collapsible **派生对话 (n)** block holding that row's own direct children. A derived conversation
+keeps its own subagents *and* its own derived conversations inside its own block, one step further in,
+so a fork of a fork is nested where it belongs instead of appearing in a second list that only shares
+a heading with its parent.
+
+**The duplicated rows are gone.** 0.3.7 drew each family twice over, once per relation, each pass
+walking the whole forest: a subagent hanging under a fork was listed both flat in the root's 子智能体
+branch and again inside its real parent. One forest is now built once (`buildForest`) and drawn once
+(`FamilyTree`), so every row is drawn by exactly one parent — which is what makes the shape readable.
+
+**Every row's checkbox means its own subtree.** A row is ticked when everything below it is ticked,
+mixed when only part of it is, and pressing it takes or clears that whole subtree; a block's checkbox
+covers the rows the block lists. The old "selected roots plus excluded children" pair is gone: the
+delete set is one set of ids, so the picture and the count can no longer drift apart.
+
+**In the bulk dialog a child can now be ticked on its own.** Every ticked row whose parent is not
+ticked is sent as a delete root of its own, carrying the ticked rows below it — so ticking a single
+subagent deletes just that subagent, and ticking a parent takes its selected family with it.
+
+**Each row carries its kind's glyph**: a document for a conversation, a robot head for the 子智能体
+block and a person for a subagent, a chain for the 派生对话 block and a chat bubble for a derived
+conversation — 16px outline paths, `fill: none`, `stroke: currentColor`, matching the icon set they
+sit beside. Nothing else changed: the nesting is still the indentation alone, one step per level, with
+no connectors and no guide lines.
+
+## 0.3.7
+
+**The connector lines are gone.** The tree's nesting is the indentation alone: one step per level, the
+same reading the rest of the sidebar uses. A drawn guide line under every parent added nothing the
+indent did not already say, and it made the rows busier than the list they sit in.
+
+Everything else from 0.3.6 stands: row 1 is this conversation, row 2 is its own subagent branch, row 3
+is the forked conversations with each fork's subagents inside it and a fork of a fork nested in its
+parent's block.
+
+## 0.3.6
+
+**The picker is the family tree now, drawn as one.** 0.2.1's two flat lists could not say what the
+reference layout says, so the dialog is drawn that way from the top down:
+
+- row 1 is this conversation, carrying the whole family's checkbox and named as the sidebar names it;
+- row 2 is one collapsible **子智能体 (n)** branch holding this conversation's own subagents;
+- row 3 is one collapsible **派生对话 (n)** branch, and each fork inside it keeps *its own* subagent
+  branch — so a fork of a fork is drawn inside its parent's block, indented one more step, instead of
+  being listed beside it. A subagent that spawned a conversation keeps that conversation inside the
+  subagent's own block for the same reason.
+- Guide lines drop from each parent to the children it draws, and indent tracks the tree, so a level-3
+  row reads as hanging off the level-2 row above it and not merely as "somewhere deeper".
+
+**The layout came from the sketch, not the data model.** The Host still answers one deepest-first
+list; the client arranges it into a tree and draws each branch as a *view* of that tree, indented from
+the nearest ancestor the branch actually draws. Nothing is ever indented under a row that is not on
+screen.
+
+**Ticks are derived, not stored twice.** A row is in the delete set when it is a selected root or sits
+beneath one. A subagent is a Session of its own, so a fork's checkbox reports the subagents under it
+without claiming them for a second delete — which is what kept the footer's count honest.
+
+## 0.3.5
+
+**A group now shows its own nesting.** 0.3.4 arranged the family as one tree but then filtered it into
+the two groups, and filtering flattened the tree: a level-2 child stayed indented under a level-1
+parent the group did not draw, so nothing on screen said which level-1 child it belonged to.
+`groupNodes` walks the arranged family in pre-order and counts each group's indent from the nearest
+ancestor *that group draws*, so a parent is followed by its own children, one step in, and the next
+family starts at the top of the column again. A group's checkbox, its root rows and the delete payload
+are unchanged: a picked row still answers to the same root it did before.
+
+**The family's read failures are reported, not swallowed.** The descendant list comes from two durable
+sources, and either one failing used to be invisible — the dialog simply drew fewer rows, which is
+indistinguishable from a conversation that genuinely has no children. `/inspect` now carries the
+warnings it collected (a catalog that would not open, a branch that could not be read), and the
+per-Session dialog prints them above the list.
+
+## 0.3.4
+
+**The per-Session picker is 0.2.1's layout again, with the lineage fixed.** 0.3.2 removed the two
+collapsible groups to fix a nesting bug; that threw away a shape that was doing its job, so the groups
+are back: one master row, then *subagent conversations* and *forked conversations*, each with its own
+count, its own checkbox and its own disclosure caret, and every row keeps its title, its id tail and
+its state badges.
+
+**What actually changed is where a row's position comes from.** Both 0.2.1 and 0.3.2 drew rows in the
+order the Host sent them, and the Host sends the family deepest-first because that is the order its
+own delete walk wants. Splitting that into groups put a grandchild in one group and its parent in
+another, where the grandchild became a top-level row and drew indented above the row it hangs under.
+The whole family is now arranged once — every row follows the row it hangs under, with the depth
+counted from the nearest row the picker actually draws — and only then split by relation, so each
+group keeps its own order without ever inverting a parent and its child.
+
+**Indentation is one step per level.** Rows are indented by the arranged depth alone (16px a level, the
+same step the bulk dialog uses), where 0.2.1 added a fixed extra level for every row: a
+one-level-deep child read as though it hung off something that was not there.
+
+## 0.3.3
+
+**Missing subagents in the per-Session dialog, fixed at the source.** The family was read from two
+places, and the subagent half leaned on `ctx.subagents.listDescendants`, which walks that service's
+own session store: when that lookup is unavailable, the call throws and *every* subagent disappears
+from the dialog at once, leaving only the forked conversations the header lineage names. The catalog
+is now read the way the Subagent runtime itself reads it — per parent, from that parent's own
+`subagentCatalog` projection through `sessionQuery.observeSession` — and walked from the target
+downwards. The service call is still made, merged by closest depth, so neither source is a single
+point of failure. Observation leases are freed through `Symbol.dispose` in a `finally`: the lease has
+no `release()`, and a walk that never disposed would pin every parent it read in the query cache.
+
+**Nesting now comes from the right parent.** Because the walk descends through each parent's own
+catalog, a subagent a *child conversation* spawned is listed under that child rather than under the
+target, and the header lineage now descends through children the catalog did not produce too. So the
+dialog draws one family per level:
+
+```
+母会话
+  子代理
+  子会话
+    子会话 1 的子代理
+  子会话 2
+    子会话 2 的子代理
+```
+
+## 0.3.2
+
+**The 子 / 母 label is gone.** The nesting reads from indentation alone, as it does in the rest of the
+sidebar. A family shows its shape: one step of indent per level, parents above their own children.
+The catalog still reports `hasChildren` and the family counts, so nothing else had to change.
+
+**The per-Session picker draws the family as one tree.** It used to split the descendants into two
+collapsible groups by relation — *subagent conversations* and *forked conversations* — and arrange
+each group on its own. A grandchild whose parent landed in the other group was therefore drawn as a
+top-level row, indented, above the row it actually hangs under. The family is now arranged as a whole
+with the same rule the bulk view uses, so every row follows the row it hangs under and the
+indentation is the nesting. The per-kind groups and their collapse controls went with it: the list is
+one tree, and the master checkbox still clears or takes the whole family.
+
+## 0.3.1
+
+Four fixes to the bulk view, three of them visible on first use.
+
+**The glyph's colour now matches its neighbours.** The control was drawn as the source SVG is
+authored — a filled glyph — while the shipped product icon set is outline-only (`fill: none`,
+`stroke: currentColor`, `strokeWidth: 1` on a 16px box). A filled path painting a 32-unit outline
+shape rendered as a blob at 16px, so the button looked empty beside the search icon. The glyph is now
+stroked in the icon set's own convention, with the stroke scaled for the halved viewBox.
+
+**Every row carries its 子 / 母 mark.** A conversation with no children of its own in the list left
+the mark blank. A row that is not a child now reads as 母 by default, so the three states are 母,
+子, and 子母 for a child that has children of its own. The mark's cell is sized for two characters, so
+子母 no longer shifts the title along.
+
+**Names come from the Session, not from "untitled".** The title read was wrong: the folded snapshot
+is `{ session, title: { title, … } }`, and the code read `value.title` — an object, which failed its
+own string check, so every Session reported no title and both dialogs fell back to *untitled*. Rows
+now resolve a display name the way the sidebar does: the durable title when the log carries one, else
+the final segment of the project directory, else the id. That fixes the bulk list and the 0.2.1
+per-Session dialog together, the latter including its subagent and forked children, which now read as
+the project directory rather than *untitled* when they were never renamed.
+
+**Lineage children can carry their own directory.** The descendant walk now passes each child's
+`cwd` from its header, so a descendant that was never named falls back to its project directory
+before falling back to its id.
+
+## 0.3.0
+
+One control beside the workspace search icon deletes many conversations at once.
+
+**A bulk entry beside the search icon.** The sidebar's workspace header gains a trash control, drawn
+from `deleting icon.svg`, immediately left of the search icon. It opens one dialog for every
+conversation the Host knows.
+
+**The list is grouped by Workspace and keeps lineages together.** Rows are sectioned by the Workspace
+that owns the conversation's directory, in the registry's own order, with one "未归类" section for
+conversations no Workspace owns. Inside a section, parents lead their children, indented by lineage
+depth. Every row leads with the blue **子** / **母** mark: `母` for a conversation with children in
+this list, `子` for one spawned as a subagent or forked off another, `子母` for both.
+
+**Selection follows the family, per row.** Ticking a parent takes its whole family with it; ticking a
+child selects it on its own. A child can be taken back off a ticked family without untick-ing the
+parent, and the footer always states how many conversations the press will delete. The dialog carries
+the same "stop unfinished work first" choice the single-Session dialog offers.
+
+**API.** `GET /catalog` answers
+`{ ok, workspaces: [{ key, workspaceId, title, path, sessions[] }], totals }`, and each session row
+carries `id`, `kind` (`root` / `subagent` / `derived`), `depth`, `parentId`, `hasChildren`, `family`,
+`subagents`, `derived`, `title`, `cwd`, `open`, `agent`, `running` and `activity`.
+`POST /delete-batch` takes `{ roots: [{ sessionId, descendants? }], stop? }` and answers
+`{ ok, roots, removed[], failed[] }` — one entry per root, so a failing root is reported without
+aborting the rest.
+
+**Where the control is mounted, and why.** `sidebar.workspaces` is a `single` slot, so a second
+registrant would shadow the shipped browser instead of sitting beside it. The plugin therefore
+registers in `sidebar.footer.action` (which renders nothing itself) and mounts its control into the
+browsing region's own search slot through a portal and one `MutationObserver`, re-creating the
+control whenever React re-renders that header. The insertion carries no authority: it only opens the
+dialog, and the two Host routes above do all the work. If a future harness renames that slot's CSS
+class, the control stops appearing and nothing else changes.
+
+**Unchanged.** The per-Session "⋯" menu entry and its descendant picker behave exactly as in 0.2.1;
+the bulk path calls the same delete for each selected conversation.
+
+## 0.2.1
+
+Deleting a conversation is a choice now, not a take-it-all.
+
+**Pick what goes with it.** The confirmation dialog lists the session's whole family and lets you
+choose:
+
+- one **delete all** checkbox, with an indeterminate state when the selection is partial;
+- one collapsible group per relation — *subagent conversations* and *forked conversations*;
+- one checkbox per descendant, indented by lineage depth, labelled with its title and the tail of its
+  id, and badged when it is open or still has work running.
+
+Confirming posts exactly the ticked ids, and the button states how many conversations will go.
+Unticked descendants survive as conversation roots.
+
+**The family is complete and the selection is validated.** Descendants come from the header lineage
+every Session carries (`SessionHeader.parentSession`) — which covers subagent sessions, forked
+conversations, and the child Sessions Agent Teams provisions — unioned with the durable
+`subagentCatalog` projection for children whose own header no longer reads. The Host validates the
+client's selection against its own walk, so a request can only ever name Sessions in that lineage
+(`400 unknown-descendant` otherwise). Omitting the field still means "all of them".
+
+**A gate bug, fixed.** Running work was only checked for the target Session, but DSH's archive
+admission answers per Session: a descendant's running turn or background job was invisible, so a child
+could be deleted mid-run. Every Session in the delete set is now asked, the refusal names each busy
+Session (`activeSessions` in the details, badges on the rows), and `stop: true` dispatches
+`workspace/session-stop` for all of them.
+
+**Shells no longer outlive their conversation.** Terminals belong to no admission family, and the
+service only reaps them when the Agent is released — which can be long after the log is gone. Each
+deleted Session's terminals are now closed, reported as `terminalsKilled`.
+
+**API.** `GET /inspect` answers with `descendants: { count, subagents, derived, truncated,
+maxDeletable, items[] }`, each item carrying `id`, `kind`, `depth`, `parentId`, `title`, `open`,
+`agent`, `running` and its own `activity`. `POST /delete` takes `{ sessionId, stop?, descendants? }`
+and answers with `kept`, `terminalsKilled` and `warnings` beside the per-Session reports. The
+request-body ceiling is 64 KiB so a few hundred ids fit, and the 200-per-request cap applies to the
+selection rather than to the whole family.
+
+**Audited, deliberately unchanged.** Attachment blobs stay (content-addressed and shared; the service
+has no reference counting), and the derived search index keeps reconciling itself.
+
+## 0.2.0
+
+- **Forked conversations are deleted with their source.** A descendant is now read from the header
+  lineage every Session carries (`SessionHeader.parentSession`), which DSH writes for both
+  relations: the Subagent runtime sets it with `origin: 'subagent'`, and a fork sets it with
+  `isSeeded`. 0.1.0 walked only the subagent catalog, so a conversation forked off the deleted one
+  survived.
+- The confirmation dialog names what goes with the delete by kind — *N subagent conversations* and
+  *N conversations forked off it* — so deleting a family is never silent.
+- `/inspect` reports `descendants: { count, subagents, derived, ids, capped }`.
+- Each descendant report in the delete response carries its `kind` (`subagent` / `derived`).
+- The lineage walk is breadth-first with a visited set and a depth cap: DSH's own lineage traversal
+  has no guard against a hand-edited `parentSession` cycle.
+
+## 0.1.0
+
+First release.
+
+- Adds a **Delete conversation** row (order 500) to every session's `⋯` menu, with a confirmation
+  dialog that states the session's real state before committing.
+- Removes the session's artifact directory (every retained format generation), its workspace
+  account, its archive/pin membership, and its projection-cache record, then emits
+  `api-session/removed` so connected pages drop the row at once.
+- Removes subagent descendants too, deepest first, collected before anything is deleted and capped
+  at 200 sessions per delete.
+- Gates on running work only (DSH's own `workspace/session-activity` admission), with a
+  **Stop and delete** path that dispatches `workspace/session-stop` first.
+- Deletes sessions the Host still holds open, instead of refusing them: measured on Windows, `rm`
+  succeeds with the append handle open and later appends do not resurrect the file.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 陆知辰 (Lzcdebear)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# better-dsh-session-deletetool
+
+**Delete a conversation from DeepSeek Harness — DSH ships archive only.**
+
+[中文说明](README.zh-CN.md)
+
+---
+
+## Why this exists
+
+DSH can only *archive* a conversation. Archiving hides the row from the sidebar and keeps every
+artifact: the log, the workspace account, the projection checkpoint all stay on disk, and the
+conversation can be restored at any time. The persistence seam has no deletion API at all —
+`@deepseek-ai/dsh-session-persistence-jsonl` states it plainly:
+
+> **Nothing deletes session files** — logs accumulate under `root` until removed externally; the
+> seam has no deletion API.
+
+So a long-lived profile accumulates conversations forever. This plugin adds the missing step: a
+**Delete conversation** row in each session's `⋯` menu that really removes the data — and the dialog
+it opens is also the one place that shows a conversation's whole family before you touch it.
+
+## What it deletes
+
+For the chosen session, the Host half:
+
+1. **removes the session's artifact directory** — the current log, every retained historical format
+   generation, and any session-local file in it (`ctx.sessionPersistence.locate(header)` gives the
+   path);
+2. **removes the descendants you selected** — child sessions are sessions of their own with their own
+   logs. DSH records every child in its parent's header (`SessionHeader.parentSession`), and writes
+   that field for every relation it creates: the Subagent runtime sets it with `origin: 'subagent'`,
+   a fork sets it with `isSeeded`, and Agent Teams resolves its roster through the same field. The
+   plugin walks that lineage breadth-first and unions it with the durable `subagentCatalog`
+   projection (`ctx.subagents.listDescendants`), so a child whose own header no longer reads is still
+   named. Descendants are deleted **deepest first**, gathered *before* anything is removed, and only
+   the ticked ones go — up to 200 per request;
+3. **drops the workspace account** — the id leaves every Workspace record's `sessionIds`
+   (`Workspace.detachSession`) and the registry-global archive and pin sets;
+4. **drops the projection checkpoint** — the `session_projcache` domain record and its `<id>.json`
+   file;
+5. **closes the shells the session owned** — `ctx.terminals` are part of no admission family, and the
+   service only reaps them when the Agent is released, which can be long after the log is gone;
+6. **tells connected pages** — one `api-session/removed` per removed id, the same event the shipped
+   Session controller emits when a Session is disposed, so the rows leave the sidebar immediately.
+
+### Seeing the family, and choosing what goes with it
+
+The sidebar lists a subagent session and a derived conversation as rows of their own, and nothing there
+says which conversation spawned them; DSH itself never draws that relation. This dialog is the one
+place it is drawn: the session's whole family as **one tree**, the branches below the branches
+included.
+
+- row 1 is this conversation, carrying the whole family's checkbox and named as the sidebar names it;
+- row 2 is one collapsible **Subagents (n)** branch holding the subagents this conversation spawned;
+- row 3 is one collapsible **Forked conversations (n)** branch, and each fork inside it keeps *its own*
+  Subagents branch — so a fork of a fork is drawn inside its parent's block, one step further in,
+  instead of being listed beside it. A subagent that spawned a conversation keeps that conversation
+  inside the subagent's own block for the same reason;
+- every row has a checkbox, its name and the tail of its id, and is badged when it is open or has
+  unfinished work. Names follow the sidebar's own rule — the durable title, else the final segment of
+  the project directory, else the id — so nothing reads as *untitled*;
+- the nesting is the **indentation** alone, one step per level: a parent is followed immediately by the
+  children it draws, so a level-3 row reads as hanging off the level-2 row above it rather than merely
+  as "somewhere deeper".
+
+A row's checkbox covers **its own subtree**: ticked when everything below it is ticked, mixed when only
+part of it is, and pressing it takes or clears that whole subtree. A block's checkbox covers the rows
+the block lists. The delete set is one set of ids, with no second "excluded rows" state beside it, so
+the picture and the footer's count cannot drift apart.
+
+Leads that could not be read are reported above the list (a branch whose directory would not open, for
+example) instead of quietly costing rows: a missing row and a conversation that genuinely has no
+children used to look exactly alike.
+
+Confirming posts exactly the ticked ids and the button states how many conversations will go.
+Unticked descendants survive as conversation roots. The selection is validated against the Host's own
+walk, so a request can only ever name Sessions in that lineage. A fork is a conversation in its own
+right, which is exactly why it is listed with a checkbox instead of being taken silently.
+
+### Deleting in bulk
+
+A trash control sits in the workspace section header, immediately **left of the search icon** (it
+draws the `deleting icon.svg` glyph). It opens one dialog over every conversation the Host knows:
+
+- **Sectioned by Workspace**, in the registry's own order, each headed by the Workspace title and its
+  conversation count; conversations no Workspace owns land in a final **Ungrouped** section.
+- **Each conversation is drawn as the same tree the single-session dialog draws**: under a row come its
+  collapsible **Subagents (n)** and **Forked conversations (n)** blocks, and a derived conversation
+  carries its own level inside its own block, so the hierarchy is the indentation alone.
+- **Names follow the sidebar's own rule**: the durable title when the log carries one, else the final
+  segment of the project directory (for example `Project_lzc`), else the id. A conversation that was
+  never renamed therefore reads as its directory rather than as *untitled*.
+- **Selection follows the subtree, and a child can be deleted on its own.** Ticking a parent takes the
+  ticked rows below it; ticking one subagent without its parent sends that subagent as a delete root of
+  its own and leaves the parent alone. The footer button always states how many conversations the press
+  will delete.
+
+The dialog carries the same **stop unfinished work first** switch as the single-session one, on by
+default. Confirming runs the delete above once per ticked root; a root that fails is listed and the
+rest still go.
+
+### What blocks a delete, and what does not
+
+**Running work blocks it — being open does not.** The gate is DSH's own archive admission, the
+`workspace/session-activity` waterfall: the Agent registry reports a running turn, the job registry
+reports background jobs, the Subagent runtime reports running descendants, Schedule reports active
+reminders. The question is asked **once per Session in the delete set**, because the admission answers
+per Session: a descendant's running turn or background job is not reported when only the target is
+asked. The dialog names what is still running — on each row and in the summary — and offers
+**Stop and delete**, which dispatches `workspace/session-stop` for every busy Session first, exactly
+what `archiveSession(id, { stopActivity: true })` does.
+
+A session the Host still holds open (`ctx.sessions` / `ctx.agents`) is deleted anyway. Measured on
+Windows: `rm` succeeds while the append handle is open, the directory entry disappears at once, and
+later appends land in the unlinked file instead of resurrecting it. An earlier version refused such
+sessions with "switch away first", which wrongly blocked conversations that were not on screen.
+
+### Known limits
+
+- **Attachment blobs are not removed.** Uploaded images and files live in
+  `~/.dsh/attachments/v1/objects/<hash>`, a content-addressed store shared by sessions, and the
+  service has no reference counting, so those blobs stay.
+- **The search index looks after itself.** `dsh-session-query-sqlite` is a derived index that
+  reconciles against persistence on every search, so a deleted source stops being returned from the
+  next search on.
+- **A held-open session may leave one inert cache record.** If the Host still owns the session when
+  it is deleted, its disposal can write one more projection checkpoint. That record is never read
+  (no log means no session) — a few tens of KB of dead file.
+- **Plugin code changes need a DSH restart.** In a profile whose HMR does not watch module files,
+  replacing the code of an installed bundle requires a restart. The client half only needs a page
+  refresh.
+
+## Install
+
+Everything below goes through DSH's own plugin manager, which accepts an install spec
+(`@deepseek-ai/dsh-plugin-manager`): a registry name, a git host shorthand, a repository URL, a
+tarball, or an absolute local path. Pick whichever route your network allows.
+
+### 1. Straight from GitHub (needs github.com reachable)
+
+Spec:
+
+```
+github:Lzcdebear/better-dsh-session-deletetool
+```
+
+or, equivalently:
+
+```
+https://github.com/Lzcdebear/better-dsh-session-deletetool
+```
+
+Give it to DSH:
+
+- **In the app:** Settings → Plugins → the install entry, paste the spec. (The Plugin Manager UI and
+  the `plugin_manager` tool take exactly the same spec string.)
+- **Through an agent session:** ask the agent to install it — the tool call is `plugin_manager` with
+  `action: "install_bundle"` and `target: "github:Lzcdebear/better-dsh-session-deletetool"`.
+
+Pin a ref with `#`: `github:Lzcdebear/better-dsh-session-deletetool#v0.1.0`.
+
+If the connection check fails, DSH reports a bounded log path. On a network where github.com is not
+reachable, use route 2 or 3 — or point git at your proxy first
+(`git config --global http.proxy http://127.0.0.1:7890`).
+
+### 2. From a local copy (works offline)
+
+Download the repository (ZIP or `git clone`), unpack it anywhere, then install the **absolute
+directory**:
+
+```
+plugin_manager { action: "install_bundle", target: "D:\\plugins\\better-dsh-session-deletetool" }
+```
+
+DSH records a `link:` dependency and reloads the profile. This is the route used to develop the
+plugin, and the one to use behind a restrictive network.
+
+### 3. From the release tarball
+
+```
+https://github.com/Lzcdebear/better-dsh-session-deletetool/archive/refs/heads/main.tar.gz
+```
+
+Same install entry as route 1; useful when git is unavailable but HTTPS is not.
+
+### After installing
+
+The Host half loads with the profile. The Client half appears after the page is refreshed. The row
+shows up in the session `⋯` menu as **删除会话 / Delete conversation**.
+
+To remove the plugin again, use the same manager:
+`plugin_manager { action: "remove_bundle", target: "better-dsh-session-deletetool" }` (the bundle key is the
+package name).
+
+## Usage
+
+1. Open the `⋯` menu on any session row and pick **Delete conversation**.
+2. The dialog asks the Host for the session's real state and states it: what will be deleted,
+   whether the Harness still holds it open, and what is still running.
+3. It then draws the whole family as a tree to choose from: this conversation on its own row, then its
+   **Subagents (n)** and **Forked conversations (n)** blocks, each derived conversation carrying its own
+   level inside its block, and a checkbox on every row (title, id tail, state badge). Untick whatever
+   you want to keep.
+4. Confirm. The button states how many conversations will go; if work is running it reads
+   **Stop and delete** and stops that work first.
+5. The rows leave the sidebar at once, and the data is gone from disk.
+
+For bulk: press the trash control in the workspace section header, **left of the search icon**, tick
+conversations in the Workspace-sectioned list (ticking a parent brings its children, a child can be
+ticked or unticked on its own), then confirm.
+
+## HTTP surface
+
+The Client half reaches the Host over four same-origin `exact` routes on `ctx.webServer`. A
+build-free plain-JavaScript bundle cannot declare a typed `ctx.remote` namespace (that needs
+generated Typert descriptors), so this uses the same transport the community plugin `dshmarket`
+uses.
+
+| Route | Method | Purpose |
+|---|---|---|
+| `/better-dsh-session-deletetool/inspect?sessionId=…` | GET | `stored` / `open` / `agent` / `running` / `activity` / `artifactDirectory` / `warnings` (the leads that could not be read, so a missing branch is never mistaken for a childless one), and `descendants` = `{ count, subagents, derived, truncated, maxDeletable, items[] }` where each item carries `id`, `kind`, `depth`, `parentId`, `title`, `open`, `agent`, `running` and its own `activity` |
+| `/better-dsh-session-deletetool/delete` | POST | body `{ sessionId, stop?, descendants? }` — `descendants` omitted means the whole family, an empty array means the session alone; returns `removed`, `descendants` (each with its `kind`), `kept`, `stoppedActivity`, `terminalsKilled`, `warnings`, `runtime`, `activity`. A name outside the family is refused with `400 unknown-descendant` before anything is removed |
+| `/better-dsh-session-deletetool/catalog` | GET | `{ ok, workspaces: [{ key, workspaceId, title, path, sessions[] }], totals }`; each session row carries `id`, `kind` (`root` / `subagent` / `derived`), `depth`, `parentId`, `hasChildren`, `family`, `subagents`, `derived`, `title`, `cwd`, `open`, `agent`, `running`, `activity`. Section order is the registry's own Workspace order, and the section whose `workspaceId` is `null` is Ungrouped |
+| `/better-dsh-session-deletetool/delete-batch` | POST | body `{ roots: [{ sessionId, descendants? }], stop? }`, each root running the single-session delete once; returns `{ ok, roots, removed[], failed[] }`. A failing root is reported as one `failed` entry and the rest are still attempted. At most 200 roots per request |
+
+All four routes carry their own same-origin gate: `Host` must be loopback, `sec-fetch-site` must not
+be `cross-site`, and a present `Origin` must match `Host`. Another site's page cannot reach them.
+
+## Layout
+
+| File | Role |
+|---|---|
+| `host.js` | Host half: the four routes, artifact/accounting/cache removal, the subagent subtree, and the Workspace-sectioned catalog |
+| `client.js` | Client half: the `sidebar.workspaces.session.menu.item` row (order 500), the bulk control, and the two `shell.overlay` dialogs |
+| `cordis.patch.yml` | Inserts the Host row into the profile's layer stack |
+| `test/host.test.mjs` | Route tests over real temporary directories |
+| `icon.svg` | Plugin artwork (the bulk control draws `deleting icon.svg`) |
+
+Styles use only host theme tokens (`--dsw-alias-*`), so light and dark both read; the UI is
+localized (English / 简体中文) through the Client locale service.
+
+Why the bulk entry is not a slot registration of its own: `sidebar.workspaces` is a `single` slot, so
+a second registrant would **shadow** the shipped session browser instead of sitting beside it. The
+Client half therefore registers in `sidebar.footer.action` (rendering nothing there) and mounts its
+control into the browser's own search cell through a portal and one `MutationObserver`, which
+re-creates the control when React re-renders that header. That insertion carries no authority beyond
+opening the dialog; the two Host routes do the work. If a future harness renames that cell's CSS
+class, the control stops appearing and nothing else changes.
+
+## Development
+
+```sh
+node --test test/host.test.mjs
+```
+
+The tests drive the real `apply()` registration against fake Host services and real temporary
+directories: deletion, the running-work gate and its stop path, the subagent subtree, the inspect
+report, and the refusal paths (bad id, bad body, wrong method, cross-site origin).
+
+## License
+
+[MIT](LICENSE)
+
+## Author
+
+- Bilibili: <https://space.bilibili.com/220996778>