dsh-plugin-session-cleaner 0.2.0 → 0.3.2

package/README.md

@@ -42,20 +42,35 @@ DSH 本身没有任何删除会话的途径：`sessionPersistence` 只有 `creat
 - **不能删除当前打开的会话**：UI 禁用入口，Host 侧独立再拒一次（`guard` 参数），Tool 也拒绝把自己所在的会话作为目标。
 - **运行中的会话先停止再删**：否则内存里的 Agent 会继续往刚删掉的日志追加写入，残留一个半截会话。若在超时内无法停止，**整个操作中止，一个文件都不删**。
 - **递归删除子代理会话**：通过日志头部的 `parentSession` 字段展开全部后代，避免产生永远无法访问的孤儿数据。
-- **先摘注册表、后删文件**，并且计划中的注册表引用先摘除，保证界面不会出现「看得见、点开报错」的空壳行。
+- **注册表摘除走两条路**（见下节「删除如何立即反映到界面」）：宿主的 `workspaceRegistry` 服务在线时，摘除通过 `unarchiveSession` / `detachSession` 走**内存注册表**（它同时是 `workspace.json` 在删除期间的唯一写者），并在文件删除**之后**执行；服务不可用时回退为删除前原子改写 `workspace.json` 文件，保证重启后不会出现「看得见、点开报错」的空壳行。
+
+## 删除如何立即反映到界面
+
+DSH 侧边栏的会话行由两个数据源合成：行的**存在**来自客户端 `sessions` 服务的列表快照（只在连接建立时通过 `session/list` 拉取一次，而 Host 的 `session/list` 每次都实时扫盘），行的**分组/归档/置顶**来自 `workspaceController` 的 follow 流（内存注册表投影）。直接改磁盘文件两边都不会察觉——官方 README 明确把「外部变更延迟可见」列为已知限制。
+
+因此删除的收尾是两步正规通道：
+
+1. **Host 侧**（动态注入 `workspaceRegistry`，不在顶层 `inject` 里——缺服务的组合仍要能激活插件）：对每个已删 id 先 `ctx.emit('api-session/removed', id)`——宿主 session-controller 释放会话时用的同一个事件，客户端收到后在**本地**移除该行，无 RPC 往返；随后依次 `unarchiveSession`（幂等，顺带清置顶互斥）、`unpinSession`（如置顶）、对记账实体 `detachSession`。emit 必须先于 registry 调用：detach 推送的 follow 增量会把仍留在快照里的行赶到「未分组」，直到 refresh 落地——先 emit，行在增量到达前就已消失。每次 registry 调用都更新内存注册表、持久化并向 follow 流推送增量；调用失败只记入结果的 `warnings`——文件已删，残留记账在下次启动时被宿主剪除，报「删除失败」反而误导。若网关不转发插件 emit 的该事件，行为退化为短暂的「未分组」闪现，不会更糟。
+2. **客户端**（动态注入 `sessions` 服务）：删除成功后先调一次 `ctx.sessions.refresh()` 重新拉取 `session/list`，**等它落定后**再对每个已确认删除的 id 调一次 `ctx.sessions.handleSessionRemoved(id)`（官方转发事件 `api-session/removed` 的同一个公开处理器）。顺序是硬约束：`refreshList()` 启动时会换新变更数组，pull 之前记录的移除（比如转发事件带来的）会在 pull 落地时被丢弃；而 Host 的 `session/list` 对**仍 attach 在内存里的会话**无条件返回（`SessionCorpus.listSessions` 的 live 优先合并，agent.cancel 只停 turn 不 detach，detach 能力只在会话创建方手里）——所以单靠 refresh，刚删的行会被合并回来的 baseline 复活进「未分组」，直到重启。refresh 之后调用 `handleSessionRemoved` 则行当场消失，且移除变更留在当前变更数组里被**下一次** refresh 重放，对仍 attach 的被删会话有一轮抗复活保护。已确认删除的 id 会在面板里登记为「已忘」清单，客户端还挂着一个**快照守卫**：订阅 `sessions` 快照变更，凡「已忘」的 id 重新出现（重连重建 baseline、任何时序竞争的复活），立即再移除一次——按实际存在判定，行掉出快照后守卫自然收敛。批量删除**部分失败**时，已确认删除的 id 同样走这条链，不会因为整体报失败而把删掉的行留在「未分组」。与此同时，客户端内的**删除信号**会通知已打开的清理面板重扫——面板的列表是挂载时的扫描快照，不重扫的话菜单删除的行会残留到面板重开为止；面板工具栏的「重新扫描」按钮兜住模型 Tool 删除这类任何客户端都看不到的变更。面板**自己发起**的删除则再快一拍：RPC 确认返回的瞬间，已确认删除的行就按结果里的 `deleted` 清单从快照里乐观移除（选中集与展开态同步收缩），随后的静默重扫不闪「正在扫描」、不清报告，只负责对账——大 profile 上一次全盘扫盘不再把「行消失」拖到几百毫秒之后。
+
+先删文件、后摘注册表的顺序是有意的：行的存在由快照决定，若先摘注册表，仍留在快照里的行会先闪现到「未分组」。Tool（`session_delete`）路径没有客户端配合，侧边栏仍需等下一次连接或重启（面板可用「重新扫描」手动对齐）。
 
 ## 安装
 
-DSH 的 profile 使用 pnpm 的 `file:` 依赖 + `dsh.profile.bundles` 声明：
+**推荐：DSH「添加插件」对话框**。在 DSH 的「插件」页打开「添加插件」，输入包名 `dsh-plugin-session-cleaner`（npm 官方源与中国大陆镜像源均已上架），确认添加后**完全退出并重启 DSH**。
+
+也可以手动声明 profile 依赖（效果等价）：
 
 ```jsonc
 // ~/.dsh/profiles/<profile>/package.json
 {
-  "dependencies": { "dsh-plugin-session-cleaner": "file:<本仓库的克隆路径>\\plugin" },
+  "dependencies": { "dsh-plugin-session-cleaner": "^0.3.2" },
   "dsh": { "profile": { "bundles": [ /* ... */, "dsh-plugin-session-cleaner" ] } }
 }
 ```
 
+随后在 profile 目录执行 `pnpm install`。本地开发则把依赖指回工作树 `"file:<本仓库的克隆路径>\plugin"`，改完代码重新 `pnpm install`。
+
 **安装后需要重启 DSH**：插件行在 Loader 配置中会先显示为 `absent`，只有重启才会激活（Host 侧与客户端 bundle 都是如此）。
 
 原因不是配置未生效，而是 Node 对 ESM 模块按 URL 永久缓存：同一进程内即便重新启用该条目，`import()` 仍会拿到首次求值的那个模块实例。因此**修改已安装的插件代码后必须重启**，`set_plugin` 的禁用/启用不足以让改动生效。
@@ -66,7 +81,7 @@ DSH 的 profile 使用 pnpm 的 `file:` 依赖 + `dsh.profile.bundles` 声明：
 node build/client.mjs                          # 构建 lib/
 node --test tests/cleaner.test.mjs \
            tests/plugin.test.mjs \
-           tests/client.test.mjs               # 51 个测试
+           tests/client.test.mjs               # 67 个测试
 ```
 
 `build/client.mjs` 是一个零依赖的极简打包器：DSH 的客户端模块系统每个包只加载**一个自包含的 `client.js`**（entry 与 chunk 之间不能同步 require 另一个相对 `client*.js`），所以相对 require 被内联，React / react-dom 则保留为平台模块请求，由 shell 冻结的模块表应答。
@@ -171,7 +186,7 @@ ctx.slots.inject('shell.overlay', () => ctx.slots.register({
 
 ### 改完必须重启
 
-Host 把每个包的 `dsh.client` 元数据缓存在内存里**直到重启**；禁用/启用条目不足以让它重新读取，`lib/client.js` 的新产物也不会被重新组合。
+Host 把每个包的 `dsh.client` 元数据缓存在内存里**直到重启**；禁用/启用条目不足以让它重新读取，`lib/client.js` 的新产物也不会被重新组合。客户端同理：Web view 会缓存旧 bundle，重启后最好再硬刷新一次（`Ctrl+Shift+R`），否则客户端跑的仍是旧逻辑——症状是「Host 行为变了、界面没变」的混合版本。
 
 权威写法见 DSH 内置 `cordis-plugin-development` skill 的 `templates/decoration/{package.json,client.js}`，以及 `@deepseek-ai/dsh-client-ui-workspace/README.zh.md` 的「Session 行 action」一节。桌面版里它们都在 `app.asar` 内，用 `tools/asar-read.mjs` 取出来。
 

package/lib/client.js

@@ -414,6 +414,14 @@ function renderMessages(React, t, messages) {
 
 module.exports = function createPanelPage(React, t, acquire, readFailure, primitives) {
   const { useState, useEffect, useMemo, useRef } = React
+  // Optional: called after a successful batch deletion so the client can
+  // re-pull its session list and drop the deleted rows from the sidebar.
+  const afterDelete = primitives?.afterDelete
+  // Optional: fires when a deletion happens OUTSIDE this panel (the sidebar
+  // menu dialog). This page's list is a scan snapshot taken on mount, so it
+  // subscribes and re-scans — otherwise deleted rows would linger here while
+  // the sidebar has already dropped them.
+  const deletionSignal = primitives?.deletionSignal
 
   return function SessionCleanerPage() {
     const [state, setState] = useState({ phase: 'loading' })
@@ -435,13 +443,24 @@ module.exports = function createPanelPage(React, t, acquire, readFailure, primit
     const [previewSize, setPreviewSize] = useState(undefined)
     const previewPanelRef = useRef(null)
 
-    const load = async () => {
-      setState({ phase: 'loading' })
-      setNotice(undefined)
+    /**
+     * (Re)scan the Host's disk. The quiet variant is the post-delete
+     * reconciliation: it keeps the current list, notice and dshHome on screen
+     * while the scan is in flight, and on failure keeps them too — the rows
+     * dropped optimistically after the delete are a better guess than a
+     * loading flash over an empty list.
+     */
+    const load = async ({ quiet = false } = {}) => {
+      if (!quiet) {
+        setState({ phase: 'loading' })
+        setNotice(undefined)
+      }
       const service = await acquire()
       if (service === undefined) {
-        const reason = readFailure?.()
-        setState({ phase: 'error', error: reason === undefined ? t('panel.serviceMissing') : t('service.mountFailed', { reason }) })
+        if (!quiet) {
+          const reason = readFailure?.()
+          setState({ phase: 'error', error: reason === undefined ? t('panel.serviceMissing') : t('panel.service.mountFailed', { reason }) })
+        }
         return
       }
       try {
@@ -449,12 +468,19 @@ module.exports = function createPanelPage(React, t, acquire, readFailure, primit
         setState({ phase: 'ready', sessions: data?.sessions ?? [], dshHome: data?.dshHome })
         setSelected(new Set())
       } catch (reason) {
-        setState({ phase: 'error', error: String(reason?.message ?? reason) })
+        if (!quiet) setState({ phase: 'error', error: String(reason?.message ?? reason) })
       }
     }
 
     useEffect(() => { load() }, [])
 
+    // Deletions from the sidebar menu invalidate this snapshot: re-scan when
+    // signaled. The cleanup happens through the subscription's disposer.
+    useEffect(() => {
+      if (deletionSignal === undefined) return undefined
+      return deletionSignal.subscribe(() => { load() })
+    }, [])
+
     // Escape closes the preview, matching the platform Modal's behaviour.
     useEffect(() => {
       if (preview === undefined || typeof document?.addEventListener !== 'function') return undefined
@@ -514,6 +540,34 @@ module.exports = function createPanelPage(React, t, acquire, readFailure, primit
       }
       try {
         const result = unwrap(await service.delete(ids, {}))
+        const deletedIds = new Set(
+          (Array.isArray(result?.deleted) ? result.deleted : [])
+            .map((entry) => entry?.id)
+            .filter((id) => typeof id === 'string'),
+        )
+        if (deletedIds.size > 0) {
+          // Optimistic removal: the Host confirmed these deletions, so the
+          // rows drop the moment the RPC returns instead of after the
+          // reconciliation scan below (a full disk walk that flashes the
+          // loading state on large profiles). A refused or partially failed
+          // delete never reaches here with the un-deleted ids included, so
+          // surviving rows stay on screen until the scan reconciles them.
+          setState((current) => (current.phase === 'ready'
+            ? { ...current, sessions: current.sessions.filter((session) => !deletedIds.has(session.id)) }
+            : current))
+          const without = (current) => {
+            const next = new Set(current)
+            for (const id of deletedIds) next.delete(id)
+            return next
+          }
+          setSelected(without)
+          setOpenSessions(without)
+          // Hand the CONFIRMED ids to the client regardless of the batch
+          // outcome — a partially failed delete still deleted these, and
+          // leaving them on the sidebar (see forgetSessions) parks them in
+          // Ungrouped until the next restart.
+          try { afterDelete?.([...deletedIds]) } catch { /* best effort */ }
+        }
         if (result?.ok === false) {
           setNotice({ kind: 'error', text: t('panel.failed', { reason: result.error ?? 'unknown' }) })
         } else {
@@ -525,7 +579,10 @@ module.exports = function createPanelPage(React, t, acquire, readFailure, primit
             }),
           })
         }
-        await load()
+        // Reconcile behind the optimistic update: the scan replaces the
+        // snapshot (and picks up deletions made elsewhere) without a loading
+        // flash, and the quiet path leaves the report above on screen.
+        await load({ quiet: true })
       } catch (reason) {
         setNotice({ kind: 'error', text: t('panel.failed', { reason: String(reason?.message ?? reason) }) })
       } finally {
@@ -859,6 +916,11 @@ module.exports = function createPanelPage(React, t, acquire, readFailure, primit
         React.createElement('button', {
           key: 'toggle', type: 'button', onClick: toggleAll, style: buttonStyle,
         }, allVisibleSelected ? t('panel.clear') : t('panel.selectAll')),
+        React.createElement('button', {
+          // The list is a snapshot; a manual re-scan also picks up deletions
+          // made through the model Tool, which no client sees happen.
+          key: 'refresh', type: 'button', disabled: busy, onClick: load, style: buttonStyle,
+        }, t('panel.refresh')),
         React.createElement('button', {
           key: 'delete',
           type: 'button',
@@ -1135,6 +1197,7 @@ const MESSAGES = Object.freeze({
     'panel.search': 'Filter by title, id, workspace or path',
     'panel.selectAll': 'Select all shown',
     'panel.clear': 'Clear selection',
+    'panel.refresh': 'Rescan',
     'panel.delete': 'Delete {count} selected ({size})',
     'panel.deleting': 'Deleting…',
     'panel.deleted': 'Deleted {count} session(s), freed {size}.',
@@ -1183,6 +1246,7 @@ const MESSAGES = Object.freeze({
     'panel.search': '按标题、id、工作区或路径筛选',
     'panel.selectAll': '全选当前列表',
     'panel.clear': '清空选择',
+    'panel.refresh': '重新扫描',
     'panel.delete': '删除选中的 {count} 个（{size}）',
     'panel.deleting': '正在删除…',
     'panel.deleted': '已删除 {count} 个会话，释放 {size}。',
@@ -1265,6 +1329,26 @@ function createConfirmStore() {
   }
 }
 
+/**
+ * A deletion happened somewhere outside the panel (the sidebar menu dialog).
+ *
+ * The panel's list is a scan snapshot taken on mount; without this signal the
+ * rows of sessions deleted through the menu would linger in an open panel
+ * until it is reopened. The panel subscribes on mount and re-scans.
+ */
+function createDeletionSignal() {
+  const listeners = new Set()
+  return {
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    emit() {
+      for (const listener of [...listeners]) listener()
+    },
+  }
+}
+
 module.exports = function createPlugin(require) {
   const React = require('react')
 
@@ -1287,6 +1371,9 @@ module.exports = function createPlugin(require) {
   /** One live dialog per activation; the overlay entry reads it. */
   const confirmStore = createConfirmStore()
 
+  /** Broadcasts deletions performed outside the panel (see createDeletionSignal). */
+  const deletionSignal = createDeletionSignal()
+
   /** Subscribe a component to the pending confirm request. */
   function useConfirmRequest() {
     const [state, setState] = React.useState(confirmStore.get)
@@ -1317,6 +1404,79 @@ module.exports = function createPlugin(require) {
       /** Human-readable reason from the most recent acquire failure, if any. */
       let acquireFailure
 
+      /**
+       * The client's session-list snapshot, when this composition publishes
+       * one. The sidebar renders its rows from that snapshot, which the shell
+       * only re-pulls on connect — so after a deletion the rows would linger
+       * until the next restart even though the files are gone. Dynamic
+       * injection: a composition without the service simply keeps the
+       * restart-based behavior.
+       */
+      let sessionList
+      try {
+        if (typeof ctx.inject === 'function') {
+          ctx.inject(['sessions'], (scope) => { sessionList = scope.sessions })
+        }
+      } catch { /* optional service: nothing to refresh */ }
+
+      /**
+       * Drop deleted sessions from the client snapshot and re-pull the
+       * baseline. Ordering is load-bearing: `handleSessionRemoved` must run
+       * AFTER the refresh settles. `refreshList()` swaps in a fresh mutation
+       * array the moment it starts, so a removal recorded earlier — from the
+       * forwarded `api-session/removed` event — is discarded when the pull
+       * lands, and the Host's session/list keeps returning a deleted session
+       * that is still attached live (cancelling its agent never detaches it;
+       * only its creator's disposer can), so the merged baseline resurrects
+       * the row into Ungrouped. Calling `handleSessionRemoved` after the
+       * refresh removes the row now AND leaves the removal mutation in the
+       * array the NEXT refresh replays against the baseline — one round of
+       * protection for as long as the session stays attached.
+       */
+      const forgottenIds = new Set()
+
+      /** Remove one deleted session's row from the client snapshot, if the snapshot service is present. */
+      const forgetSession = (id) => {
+        try { sessionList?.handleSessionRemoved?.(id) } catch { /* snapshot-only repair */ }
+      }
+
+      const forgetSessions = (sessionIds) => {
+        const ids = Array.isArray(sessionIds) ? sessionIds.filter((id) => typeof id === 'string') : []
+        for (const id of ids) forgottenIds.add(id)
+        const forget = () => {
+          for (const id of ids) forgetSession(id)
+        }
+        try {
+          const pending = sessionList?.refresh?.()
+          if (pending && typeof pending.then === 'function') pending.then(forget, forget)
+          else forget()
+        } catch {
+          forget()
+        }
+      }
+
+      try {
+        if (sessionList && typeof sessionList.subscribe === 'function' && typeof sessionList.getListSnapshot === 'function') {
+          // Last line of defense against snapshot resurrections. Any baseline
+          // rebuild (a reconnect's handleConnected, a refresh we did not
+          // trigger) drops the mutation array and re-merges the Host list —
+          // which still contains a deleted-but-attached session. Whenever the
+          // snapshot changes, re-remove every known-deleted id it still
+          // carries. Gating on actual presence keeps this convergent: the
+          // removal drops the row, so the next pass has nothing to do.
+          sessionList.subscribe(() => {
+            if (forgottenIds.size === 0) return
+            let snapshot
+            try { snapshot = sessionList.getListSnapshot() } catch { return }
+            const items = Array.isArray(snapshot?.items) ? snapshot.items : []
+            if (items.length === 0) return
+            for (const entry of items) {
+              if (forgottenIds.has(entry?.sessionId)) forgetSession(entry.sessionId)
+            }
+          })
+        }
+      } catch { /* without a subscribable snapshot, the call-side forget is the only repair */ }
+
       const readFailure = () => acquireFailure
 
       /**
@@ -1494,6 +1654,11 @@ module.exports = function createPlugin(require) {
               setError(result.error ?? 'unknown failure')
               return
             }
+            // The files are gone: drop the rows from the client snapshot (see
+            // forgetSessions) and tell an open cleanup panel to re-scan, since
+            // its list is a mount snapshot.
+            forgetSessions([sessionId])
+            deletionSignal.emit()
             confirmStore.dismiss()
           } catch (reason) {
             setError(String(reason?.message ?? reason))
@@ -1612,7 +1777,12 @@ module.exports = function createPlugin(require) {
         // to the shipped Plugins and Automation Tasks pages. `selectPanel(id)`
         // dispatches on this key, so a missing entry would make the sidebar
         // row throw on click — the two registrations below are one unit.
-        const page = createPanelPage(React, t, acquire, readFailure, { Modal, Button })
+        const page = createPanelPage(React, t, acquire, readFailure, {
+          Modal,
+          Button,
+          afterDelete: forgetSessions,
+          deletionSignal,
+        })
         ctx.slots.inject('main', () => ctx.slots.register({
           name: 'main',
           key: PANEL_ID,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-session-cleaner",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "Completely delete DSH sessions: session logs, projection cache, workspace-registry references and derived search indexes.",
   "type": "module",
   "license": "MIT",

package/src/cleaner.js

@@ -551,14 +551,24 @@ export function assertDeletable(target, allowedRoots) {
 /**
  * Execute a plan. Order is deliberate and must not be reordered:
  *   1. stop every running session,
- *   2. detach registry references,
- *   3. delete session directories and projection caches,
+ *   2. delete session directories and projection caches,
+ *   3. detach registry references,
  *   4. purge derived search indexes that can no longer be reconciled.
  *
- * `stop` is injected so this module stays testable and free of runtime coupling.
+ * Step 3 has two authorities. `options.detachRegistry(ids)` — injected when a
+ * live DSH registry service is reachable — detaches through the in-memory
+ * registry, which also updates the running app's workspace projection, and it
+ * runs AFTER the file deletions: the sidebar renders rows from the client's
+ * session-list snapshot, so detaching first would flash a still-listed row
+ * into Ungrouped before the client re-pulls the list. Without the service
+ * (offline runs, tests) the registry FILE is rewritten in place BEFORE the
+ * deletions, so no row can outlive its log across a restart.
+ *
+ * `stop` is injected the same way, so this module stays testable and free of
+ * runtime coupling.
  */
 export async function executeDeletion(roots, plan, options = {}) {
-  const { stop, now = () => Date.now() } = options
+  const { stop, detachRegistry, now = () => Date.now() } = options
   const allowedRoots = [roots.sessions, roots.storages]
   const result = {
     startedAt: now(),
@@ -566,6 +576,7 @@ export async function executeDeletion(roots, plan, options = {}) {
     registryChanges: [],
     deleted: [],
     failed: [],
+    warnings: [],
     searchIndexesRemoved: [],
     searchIndexesKept: [],
   }
@@ -585,18 +596,21 @@ export async function executeDeletion(roots, plan, options = {}) {
 
   const blocked = new Set(result.failed.map((entry) => entry.id))
 
-  // 2. Detach registry references first, so no row survives its own log.
-  let registry = await readWorkspaceRegistry(roots)
-  if (registry !== undefined) {
-    const removable = plan.targets.filter((target) => !blocked.has(target.id)).map((target) => target.id)
-    const projected = detachFromRegistry(registry, removable)
-    if (projected.changes.length > 0) {
-      try {
-        await writeJsonAtomic(roots.workspaceRegistry, projected.registry)
-        registry = projected.registry
-        result.registryChanges = projected.changes
-      } catch (error) {
-        result.failed.push({ id: '*', stage: 'registry', reason: String(error?.message ?? error) })
+  // 2. Offline registry detach: rewrite the file before deleting anything, so
+  //    no row survives its own log across a restart. The live-service path
+  //    performs this step after the deletions instead (see the docblock).
+  if (detachRegistry === undefined) {
+    let registry = await readWorkspaceRegistry(roots)
+    if (registry !== undefined) {
+      const removable = plan.targets.filter((target) => !blocked.has(target.id)).map((target) => target.id)
+      const projected = detachFromRegistry(registry, removable)
+      if (projected.changes.length > 0) {
+        try {
+          await writeJsonAtomic(roots.workspaceRegistry, projected.registry)
+          result.registryChanges = projected.changes
+        } catch (error) {
+          result.failed.push({ id: '*', stage: 'registry', reason: String(error?.message ?? error) })
+        }
       }
     }
   }
@@ -632,6 +646,28 @@ export async function executeDeletion(roots, plan, options = {}) {
     }
   }
 
+  // 3b. Live registry detach, after the deletions. Failures are REPORTED, not
+  //     fatal: the files are already gone, a stale accounting entry heals on
+  //     the next start (the registry prunes ids with no session header), and
+  //     declaring the whole deletion failed after the rows vanished would
+  //     mislead more than a warning does.
+  if (detachRegistry !== undefined) {
+    const removable = result.deleted
+      .filter((entry) => entry.kind === 'session-dir')
+      .map((entry) => entry.id)
+    if (removable.length > 0) {
+      try {
+        const detached = await detachRegistry(removable)
+        if (Array.isArray(detached?.changes)) result.registryChanges.push(...detached.changes)
+        for (const failure of Array.isArray(detached?.failures) ? detached.failures : []) {
+          result.warnings.push(`registry detach for ${failure?.id ?? '*'}: ${failure?.reason ?? 'unknown failure'}`)
+        }
+      } catch (error) {
+        result.warnings.push(`registry detach: ${String(error?.message ?? error)}`)
+      }
+    }
+  }
+
   // 4. Derived search indexes are disposable: removing unreconcilable ones is
   //    safe because they are rebuilt from the surviving logs on next search.
   for (const indexFile of plan.searchIndexes) {

package/src/index.js

@@ -78,6 +78,7 @@ function resultToWire(result) {
     registryChanges: result.registryChanges,
     searchIndexesRemoved: result.searchIndexesRemoved.map((entry) => entry.path),
     failed: result.failed,
+    warnings: result.warnings,
     summary: result.summary,
     humanBytes: formatBytes(result.summary?.bytesDeleted ?? 0),
   }
@@ -91,6 +92,16 @@ function createService(ctx) {
   const roots = rootsFor(resolveDshHome())
   const timeoutMs = stopTimeoutMs()
 
+  /**
+   * The live workspace registry, when the running DSH publishes one. Present,
+   * it becomes the single write authority over `workspace.json`: deleting ids
+   * through it updates the in-memory registry and pushes follow increments to
+   * the client, so deleted rows disappear from the sidebar without a restart.
+   * Writing the file ourselves beside it would race the registry's own
+   * read-modify-write and resurrect detached ids on its next change.
+   */
+  let liveRegistry
+
   /** Resolve a live agent for a session, if one is registered. */
   const liveAgent = (sessionId) => {
     try {
@@ -145,9 +156,69 @@ function createService(ctx) {
     }
   }
 
+  /**
+   * Detach deleted sessions through the LIVE registry service, so the running
+   * app updates its workspace projection immediately instead of on next start.
+   *
+   * Every call is idempotent on the registry side: unarchiving an id that is
+   * not archived resolves without writing, and `detachSession` filters a list
+   * that no longer carries the id. Pin and archive are mutually exclusive and
+   * archiving drops the pin, but both sets are checked anyway — belt against
+   * a registry whose invariants drifted. Failures are collected per id and
+   * reported as warnings: the files are already deleted at this point, and a
+   * stale accounting entry heals on the next start.
+   */
+  const detachViaRegistry = async (ids) => {
+    const registry = liveRegistry
+    const changes = []
+    const failures = []
+    if (registry === undefined) return { changes, failures }
+
+    let entities
+    try {
+      entities = registry.list()
+    } catch (error) {
+      return { changes, failures: [{ id: '*', reason: `registry list() failed: ${String(error?.message ?? error)}` }] }
+    }
+
+    for (const id of ids) {
+      // Remove the row from the client BEFORE the accounting detach. The
+      // detach pushes a follow increment that re-roots a still-snapshotted
+      // row into Ungrouped, where it lingers until the list refresh lands —
+      // the event makes the client drop the row locally first, with no RPC
+      // round trip. It is the same event the shipped controller emits when it
+      // disposes a session; if the gateway does not relay it, behavior falls
+      // back to the brief Ungrouped flash, never worse.
+      try { ctx.emit?.('api-session/removed', id) } catch { /* advisory */ }
+      try {
+        if (Array.isArray(registry.archivedSessionIds) && registry.archivedSessionIds.includes(id)) {
+          await registry.unarchiveSession(id)
+          changes.push({ where: 'global.archivedSessionIds', removed: 1 })
+        }
+        if (Array.isArray(registry.pinnedSessionIds) && registry.pinnedSessionIds.includes(id)) {
+          await registry.unpinSession(id)
+          changes.push({ where: 'global.pinnedSessionIds', removed: 1 })
+        }
+        for (const entity of entities) {
+          if (!Array.isArray(entity?.sessionIds) || !entity.sessionIds.includes(id)) continue
+          await entity.detachSession(id)
+          changes.push({ where: `workspaces[${String(entity.id)}].sessionIds`, removed: 1 })
+        }
+      } catch (error) {
+        failures.push({ id, reason: String(error?.message ?? error) })
+      }
+    }
+    return { changes, failures }
+  }
+
   return {
     dshHome: roots.dshHome,
 
+    /** Attach or detach the live registry service (see apply). */
+    bindRegistry(registry) {
+      liveRegistry = registry && typeof registry === 'object' ? registry : undefined
+    },
+
     /** Every session on disk with lightweight metadata, largest first. */
     async list() {
       const { records, skipped } = await scanSessions(roots)
@@ -234,8 +305,20 @@ function createService(ctx) {
         }
       }
 
-      const result = await executeDeletion(roots, planned, { stop: stopSession })
-      return { ok: result.failed.length === 0 && result.aborted !== true, ...resultToWire(result) }
+      const hasLiveRegistry = liveRegistry !== undefined
+      const result = await executeDeletion(roots, planned, {
+        stop: stopSession,
+        ...(hasLiveRegistry ? { detachRegistry: detachViaRegistry } : {}),
+      })
+      return {
+        ok: result.failed.length === 0 && result.aborted !== true,
+        // Which authority detached the registry references: 'live-registry'
+        // means the running app's projection was updated in place (the client
+        // re-pulls its session list right after this), 'registry-file' is the
+        // offline fallback that edits workspace.json on disk.
+        registrySync: hasLiveRegistry ? 'live-registry' : 'registry-file',
+        ...resultToWire(result),
+      }
     },
   }
 }
@@ -328,6 +411,20 @@ export function apply(ctx) {
   service.typertRemote = Object.freeze({ service, serviceKey: name, namespace: name })
   ctx.provide(name, service)
 
+  // Dynamic — NOT part of `inject` — so a composition without the workspace
+  // registry still activates this plugin and keeps the file-based fallback.
+  // While the service is up it is the only writer of workspace.json during
+  // deletions (see createService). The disposable is kept for symmetry with
+  // Cordis' effect semantics but the plugin lives as long as the host.
+  try {
+    if (typeof ctx.inject === 'function') {
+      ctx.inject(['workspaceRegistry'], (scope) => {
+        service.bindRegistry(scope?.workspaceRegistry)
+        return () => { service.bindRegistry(undefined) }
+      })
+    }
+  } catch { /* the composition publishes no workspace registry */ }
+
   ctx.effect(() => {
     const holder = ctx.agents?.currentInitiator?.()
     const currentSessionId = typeof holder?.id === 'string' ? holder.id : undefined