@wangxiaocuo/dsh-session-trash 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 本文件记录这个插件的所有重要变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [Unreleased]
+
+## [0.6.5] - 2026-11-11
+
+### Added
+
+- 回收站页可以清理不含会话日志的空无主对象（`POST /orphans/forget`）；可能含日志的无主对象继续保留，供人工处理。
+- CI 增加 `lib/**` 覆盖率门槛（行 85 / 分支 70 / 函数 84）和 README 的 CI badge。
+- 新增 tag 触发的 release workflow：typecheck、单测、smoke、真实 Host e2e 通过后 `npm publish --provenance` 并创建 GitHub Release；使用 npm Trusted Publishing，无需 `NPM_TOKEN`。
+
+### Changed
+
+- `GET /state` 改为纯只读；页面打开时由客户端显式调用 `POST /sweep` 触发节流维护，读请求不再可能触发永久删除。
+- 锁竞争：Host 在报 `LOCKED` 前短暂重试，客户端对 `LOCKED` 自动重试一次；`trash()` 的 lineage/preflight 移到锁外，缩短持锁时间。
+- 收紧 `lib/errors.js` 和 `lib/fsops.js` 的类型（`any` 换成 `unknown` 与具体形状）。
+
+### Tests
+
+- 覆盖页面维护扫描（成功/节流/失败）、空无主对象清理、锁重试和客户端 LOCKED 重试。
+
+## [0.6.4] - 2026-11-11
+
+### Added
+
+- e2e 支持 `DSH_E2E_DSH_BIN` 启动 npm 安装的 `@deepseek-ai/dsh` web Host，不再依赖桌面版；Linux/Windows 也能跑真实 Host 端到端测试。
+- CI 新增真实 Host e2e job（Ubuntu + Windows），失败时输出 check annotations。
+- 新增 `pnpm typecheck`（`tsc --checkJs`，先覆盖 `lib/` 和 `index.js`）并接入 CI；DSH 服务通过 `types/dsh-context.d.ts` 的 ambient 声明提供类型。
+- 新增 jsdom + 真实 React 渲染测试（`test/client-dom.test.js`），覆盖行菜单的方向键/Escape/Tab/外点关闭，以及确认对话框的焦点陷阱和焦点恢复。
+
+### Fixed
+
+- ActionMenu：Escape 不再冒泡到宿主设置弹层；Tab 会关闭菜单并让焦点自然移动；分隔符使用 `role="separator"`。
+- ConfirmDialog：打开它的行或按钮被移除后，焦点回退到列表面板，不再丢到 `body`。
+
 ## [0.6.3] - 2026-11-11
 
 ### Added
@@ -78,6 +112,8 @@
 
 - 回收站工具栏的「永久删除全部」与二次确认；`missing` 记录只移出索引，不删除会话文件。
 
+[0.6.5]: https://github.com/wangxiaocuo/dsh-session-trash/compare/v0.6.4...v0.6.5
+[0.6.4]: https://github.com/wangxiaocuo/dsh-session-trash/compare/v0.6.3...v0.6.4
 [0.6.3]: https://github.com/wangxiaocuo/dsh-session-trash/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/wangxiaocuo/dsh-session-trash/compare/v0.6.1...v0.6.2
 [0.6.1]: https://github.com/wangxiaocuo/dsh-session-trash/compare/v0.6.0...v0.6.1

package/README.en.md

@@ -1,12 +1,14 @@
 # dsh-session-trash
 
+[![CI](https://github.com/wangxiaocuo/dsh-session-trash/actions/workflows/ci.yml/badge.svg)](https://github.com/wangxiaocuo/dsh-session-trash/actions/workflows/ci.yml)
+
 [简体中文](./README.md) | English
 
 [GitHub](https://github.com/wangxiaocuo/dsh-session-trash) · [npm](https://www.npmjs.com/package/@wangxiaocuo/dsh-session-trash) · [Changelog](./CHANGELOG.md)
 
 A session trash for DeepSeek Harness. Move cold sessions out of the sidebar without deleting their logs, restore them within the retention window, or delete the logs permanently. Built for DSH 0.2.2-rc.1 on Desktop and Web. Host and Client ship in one package, with no build step.
 
-Status: feature complete. CI (GitHub Actions) runs the unit and Host smoke tests on Ubuntu (Node 20/22) and Windows (Node 22); macOS has run the end-to-end suite against a real DSH Host. The Windows and Linux DSH Hosts have not been verified manually yet, and Windows skips the cases that rely on POSIX permission bits.
+Status: feature complete. CI (GitHub Actions) runs the unit tests, the Host smoke test, and the real `dsh web` end-to-end suite on Ubuntu (Node 20/22) and Windows (Node 22), booting the Host from an npm-installed DSH runtime; macOS also ran the suite against the real desktop Host manually. Windows skips the cases that rely on POSIX permission bits.
 
 ## Features
 
@@ -113,13 +115,15 @@ All routes live under `/plugins/dsh-session-trash/api/` and are registered as ex
 
 | Method | Path | Description |
 |---|---|---|
-| `GET` | `/state` | Config, index state, entries, stats, and cleanup diagnostics; may schedule a throttled page-open cleanup |
+| `GET` | `/state` | Config, index state, entries, stats, and cleanup diagnostics (read-only; never sweeps) |
+| `POST` | `/sweep` | No body; runs one throttled page-open maintenance sweep; whether expired entries are deleted depends on `enableAutoCleanup` |
 | `POST` | `/preflight` | `{ sessionId }` returns `{ eligible: true, descendants }` or `{ eligible: false, code, message, details? }`; `descendants` is the number of hidden children that move along |
 | `POST` | `/trash` | `{ sessionId }`; moves the whole session tree (parent plus hidden subagent children) and returns `{ ok, entry }` |
 | `POST` | `/restore` | `{ sessionId, mode: 'normal' \| 'orphan' }` |
 | `POST` | `/purge` | `{ sessionId }`; permanently deletes the session log |
 | `POST` | `/purge-all` | No body; permanently deletes every entry in the trash, dropping `missing` index records only; returns `{ ok, purged, forgotten, failed }` |
 | `POST` | `/forget` | `{ sessionId }`; removes only a `missing` index entry |
+| `POST` | `/orphans/forget` | No body; removes empty unindexed object directories that hold no session log; returns `{ ok, removed }` |
 | `POST` | `/reveal` | `{ sessionId }`; opens the original workspace |
 | `POST` | `/cleanup` | No body; runs one cleanup sweep |
 | `POST` | `/rebuild` | No body; rebuilds the index only in protection mode |
@@ -165,19 +169,22 @@ The index schema is v2; a v1 index is upgraded automatically on startup and pres
 - Orphan restore never recreates the original workspace directory and never reattaches the session to a workspace.
 - Archive and pin state survive trash and restore. The Trash page does not manage either set.
 - Permanent deletion removes the session log only. Attachments, images, projection-cache rows, and search-index rows are not deleted.
+- Unindexed objects (object directories whose `meta.json` is damaged or unreadable) are never deleted automatically; the page can only clean empty leftovers that hold no session log, and anything that may contain logs is left for manual inspection.
 - `/state` returns all entry summaries in one response. Search, filtering, and paging happen in the Client.
 - There is no cross-window live push. Another window's change appears after a refresh or when the window regains focus.
-- The Windows and Linux DSH Hosts have not been verified manually; CI covers unit and Host smoke tests only. On Windows, cases that rely on POSIX permission bits are skipped, and long paths over 260 characters / symlink copying depend on system configuration (the related tests skip themselves when unsupported).
+- The desktop apps on Windows and Linux have not been verified manually; CI boots an npm-installed `dsh web` Host, so desktop-shell UI and desktop-only features (such as reveal in the file manager) are still verified on macOS only. On Windows, cases that rely on POSIX permission bits are skipped, and long paths over 260 characters / symlink copying depend on system configuration (the related tests skip themselves when unsupported).
 - macOS path comparison is case-insensitive. On a case-sensitive APFS volume, paths that differ only by case are treated as the same location.
-- Multiple DSH processes sharing one `DSH_HOME` serialize trash operations through `.lock`. A process paused for more than 10 minutes can lose the lock to another process.
+- Multiple DSH processes sharing one `DSH_HOME` serialize trash operations through `.lock`. The Host retries briefly before reporting `LOCKED`, and the Client retries once automatically; a process paused for more than 10 minutes can lose the lock to another process.
 
 ## Development
 
 ```bash
 pnpm install
-pnpm test          # unit tests
+pnpm test          # unit tests + real-DOM component tests (jsdom)
+pnpm typecheck     # tsc --checkJs (currently lib/ and index.js)
+pnpm test:coverage # coverage (CI thresholds apply to lib/**)
 pnpm test:smoke    # Host smoke test (real Cordis, plain Node)
-npm run test:e2e   # real dsh web end-to-end (needs the desktop app)
+npm run test:e2e   # real dsh web end-to-end (desktop app or npm-installed DSH)
 ```
 
 The Host smoke test wires the plugin into a real Cordis context through the `@deepseek-ai/cordis` devDependency, creates its own temporary `DSH_HOME`, and removes it afterwards; it does not need the desktop app. Set `DSH_SMOKE_KEEP=1` to keep the temporary home for debugging. `pnpm test` enumerates the test files through `test/run-unit.mjs`, so it does not depend on shell glob expansion and behaves the same on Windows and POSIX shells.
@@ -188,9 +195,19 @@ What CI verifies:
 |---|---|
 | Unit tests, Host smoke test | CI: Ubuntu Node 20/22, Windows Node 22 |
 | Package contents (`npm pack`) | CI: Ubuntu |
-| Real `dsh web` end to end | macOS + DSH 0.2.2-rc.1 (run manually) |
+| Coverage thresholds (`lib/**`, lines 85 / branches 70 / functions 84) | CI: Ubuntu Node 22 |
+| Real `dsh web` end to end (npm-installed DSH) | CI: Ubuntu, Windows (Node 22) |
+| Real `dsh web` end to end (desktop app) | macOS + DSH 0.2.2-rc.1 (run manually) |
+
+`npm run test:e2e` boots a real `dsh web` Host in a temporary `DSH_HOME` and runs the full flow. By default it discovers the desktop app in the platform's usual install locations (or uses `DSH_ELECTRON`); set `DSH_E2E_DSH_BIN` to the `lib/bin.js` of an npm-installed `@deepseek-ai/dsh` to boot the Host with plain Node instead - CI and Linux/Windows use that mode, with no desktop app required. When no Host is found it prints a skip message and exits 0. The cleanup-failure scenario that relies on POSIX permission bits is skipped on Windows. Set `DSH_E2E_KEEP=1` to keep the temporary home and logs.
+
+### Releasing (maintainers)
+
+1. Bump the version in `package.json` and update `CHANGELOG.md`, then commit and push.
+2. Create and push a tag: `git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z`.
+3. The tag runs [release.yml](.github/workflows/release.yml): typecheck, unit tests, smoke test, real-host e2e, then `npm publish --provenance` and a GitHub release.
 
-`npm run test:e2e` boots a real `dsh web` Host in a temporary `DSH_HOME` and runs the full flow. It discovers the desktop app in the platform's usual install locations, or uses `DSH_ELECTRON`; when no desktop app is found it prints a skip message and exits 0. The cleanup-failure scenario that relies on POSIX permission bits is skipped on Windows. Set `DSH_E2E_KEEP=1` to keep the temporary home and logs.
+Publishing uses npm Trusted Publishing (OIDC), so no `NPM_TOKEN` is required: add repository `wangxiaocuo/dsh-session-trash` and workflow `release.yml` under the package's Settings -> Publishing access -> Trusted publishers on npmjs.com. To use an automation token instead, uncomment the `NODE_AUTH_TOKEN` environment variable in release.yml and add the matching secret.
 
 Project layout:
 

package/README.md

@@ -1,12 +1,14 @@
 # dsh-session-trash
 
+[![CI](https://github.com/wangxiaocuo/dsh-session-trash/actions/workflows/ci.yml/badge.svg)](https://github.com/wangxiaocuo/dsh-session-trash/actions/workflows/ci.yml)
+
 简体中文 | [English](./README.en.md)
 
 [GitHub](https://github.com/wangxiaocuo/dsh-session-trash) · [npm](https://www.npmjs.com/package/@wangxiaocuo/dsh-session-trash) · [更新记录](./CHANGELOG.md)
 
 DeepSeek Harness 的会话回收站插件。冷会话可以从侧边栏移出，日志保留在本地；保留期内可以恢复，到期后自动删除日志。面向 DSH 0.2.2-rc.1 的 Desktop 和 Web，Host 和 Client 在同一个包里，不需要构建步骤。
 
-当前状态：功能已实现。CI（GitHub Actions）在 Ubuntu（Node 20/22）和 Windows（Node 22）上跑单元测试与 Host 冒烟测试；macOS 已在真实 DSH Host 上跑通端到端测试。Windows 和 Linux 的真实 DSH Host 尚未手动验证；Windows 上依赖 POSIX 权限位的用例会显式跳过。
+当前状态：功能已实现。CI（GitHub Actions）在 Ubuntu（Node 20/22）和 Windows（Node 22）上跑单元测试、Host 冒烟测试和真实 `dsh web` 端到端测试（Host 由 npm 安装的 DSH runtime 启动）；macOS 另外在真实桌面版 Host 上手动跑通过 e2e。Windows 上依赖 POSIX 权限位的用例会显式跳过。
 
 ## 功能
 
@@ -112,13 +114,15 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
-| `GET` | `/state` | 配置、索引状态、条目、统计和清理诊断；打开页面时可能触发一次节流清理 |
+| `GET` | `/state` | 配置、索引状态、条目、统计和清理诊断（只读，不触发清理） |
+| `POST` | `/sweep` | 无请求体，按节流执行一次页面维护扫描；回收站页面打开时调用，是否删除过期条目由 `enableAutoCleanup` 决定 |
 | `POST` | `/preflight` | `{ sessionId }` 返回 `{ eligible: true, descendants }` 或 `{ eligible: false, code, message, details? }`；`descendants` 是一并移入的隐藏子会话数 |
 | `POST` | `/trash` | `{ sessionId }`，移动整棵会话树（父会话 + 隐藏 subagent 子会话），返回 `{ ok, entry }` |
 | `POST` | `/restore` | `{ sessionId, mode: 'normal' \| 'orphan' }` |
 | `POST` | `/purge` | `{ sessionId }`，永久删除会话日志 |
 | `POST` | `/purge-all` | 无请求体，永久删除回收站中的全部条目；`missing` 记录仅移除索引；返回 `{ ok, purged, forgotten, failed }` |
 | `POST` | `/forget` | `{ sessionId }`，仅移除 `missing` 条目的索引记录 |
+| `POST` | `/orphans/forget` | 无请求体，删除不含会话日志的空无主对象目录；返回 `{ ok, removed }` |
 | `POST` | `/reveal` | `{ sessionId }`，打开原工作区 |
 | `POST` | `/cleanup` | 无请求体，手动执行一次清理 |
 | `POST` | `/rebuild` | 无请求体，仅在索引保护模式下重建 |
@@ -164,19 +168,22 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 - 孤儿恢复不会重建原工作区目录，也不会重新挂到工作区。
 - 归档和置顶状态会跨回收、恢复保留，回收站页面不管理这两个集合。
 - 永久删除只删除会话日志。附件、图片、投影缓存和搜索索引不会被删除。
+- 无主对象（`meta.json` 损坏或无法识别的对象目录）不会自动删除；页面只能清理其中不含会话日志的空目录，可能含日志的需要人工处理。
 - `/state` 一次返回全部条目摘要，页面在客户端搜索、筛选和分页。
 - 没有跨窗口实时推送。另一个窗口的变更要等刷新或窗口重新获得焦点后出现。
-- Windows 和 Linux 的真实 DSH Host 尚未手动验证；CI 只覆盖单元测试和 Host 冒烟测试。Windows 上依赖 POSIX 权限位的用例会跳过；超过 260 字符的长路径和符号链接复制受系统设置影响，对应用例在不支持时自动跳过。
+- Windows/Linux 的桌面版尚未手动验证；CI 用 npm 安装的 `dsh web` 覆盖真实 Host 行为，但桌面壳 UI 与桌面专属能力（例如「在文件管理器中显示」）仍只在 macOS 上验证。Windows 上依赖 POSIX 权限位的用例会跳过；超过 260 字符的长路径和符号链接复制受系统设置影响，对应用例在不支持时自动跳过。
 - macOS 的路径比较按大小写不敏感处理。在大小写敏感的 APFS 卷上，仅大小写不同的两个路径会被视为同一位置。
-- 多个 DSH 进程共享同一个 `DSH_HOME` 时，回收站操作通过 `.lock` 串行；进程暂停超过 10 分钟后，锁可能被另一个进程接管。
+- 多个 DSH 进程共享同一个 `DSH_HOME` 时，回收站操作通过 `.lock` 串行；Host 在报 `LOCKED` 前会短暂重试，客户端也会自动重试一次；进程暂停超过 10 分钟后，锁可能被另一个进程接管。
 
 ## 开发
 
 ```bash
 pnpm install
-pnpm test          # 单元测试
+pnpm test          # 单元测试 + 真实 DOM 组件测试（jsdom）
+pnpm typecheck     # tsc --checkJs（当前覆盖 lib/ 和 index.js）
+pnpm test:coverage # 覆盖率（CI 的门槛只作用于 lib/**）
 pnpm test:smoke    # Host 冒烟测试（真实 Cordis，普通 Node 即可）
-npm run test:e2e   # 真实 dsh web 端到端（需要本机桌面版）
+npm run test:e2e   # 真实 dsh web 端到端（桌面版或 npm 安装的 DSH）
 ```
 
 Host 冒烟测试通过 `@deepseek-ai/cordis` 这个 devDependency 装配真实插件上下文，自己创建并清理临时 `DSH_HOME`，不需要桌面版；设置 `DSH_SMOKE_KEEP=1` 可以保留临时目录用于排查。`pnpm test` 通过 `test/run-unit.mjs` 枚举测试文件，不依赖 shell 展开 glob，Windows 和 POSIX shell 行为一致。
@@ -187,9 +194,19 @@ Host 冒烟测试通过 `@deepseek-ai/cordis` 这个 devDependency 装配真实
 |---|---|
 | 单元测试、Host 冒烟测试 | CI：Ubuntu Node 20/22、Windows Node 22 |
 | 打包内容（`npm pack`） | CI：Ubuntu |
-| 真实 `dsh web` 端到端 | macOS + DSH 0.2.2-rc.1（手动执行） |
+| 覆盖率门槛（`lib/**`，行 85 / 分支 70 / 函数 84） | CI：Ubuntu Node 22 |
+| 真实 `dsh web` 端到端（npm 安装的 DSH） | CI：Ubuntu、Windows（Node 22） |
+| 真实 `dsh web` 端到端（桌面版） | macOS + DSH 0.2.2-rc.1（手动执行） |
+
+`npm run test:e2e` 会启动真实 `dsh web` Host，在临时 `DSH_HOME` 中跑完整流程。默认按平台在常见安装位置查找桌面版（也可以用 `DSH_ELECTRON` 指定）；设置 `DSH_E2E_DSH_BIN` 指向 npm 安装的 `@deepseek-ai/dsh` 的 `lib/bin.js` 时，改用普通 Node 启动 Host——CI 和 Linux/Windows 都走这条路径，不依赖桌面版。找不到 Host 时打印跳过信息并以 0 退出。依赖 POSIX 权限位的「清理失败」场景在 Windows 上会跳过。设置 `DSH_E2E_KEEP=1` 可以保留临时目录和日志。
+
+### 发布（维护者）
+
+1. 更新 `package.json` 版本和 `CHANGELOG.md`，提交并推送。
+2. 打 tag 并推送：`git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z`。
+3. tag 会触发 [release.yml](.github/workflows/release.yml)：跑 typecheck、单测、smoke 和真实 Host e2e，然后 `npm publish --provenance` 并创建 GitHub Release。
 
-`npm run test:e2e` 会启动真实 `dsh web` Host，在临时 `DSH_HOME` 中跑完整流程。脚本会按平台在常见安装位置查找桌面版，也可以用 `DSH_ELECTRON` 指向其他 Electron 可执行文件；找不到桌面版时打印跳过信息并以 0 退出。依赖 POSIX 权限位的「清理失败」场景在 Windows 上会跳过。设置 `DSH_E2E_KEEP=1` 可以保留临时目录和日志。
+发布使用 npm Trusted Publishing（OIDC），不需要 `NPM_TOKEN`：在 npmjs.com 的包设置 → Publishing access → Trusted publishers 里添加仓库 `wangxiaocuo/dsh-session-trash` 和 workflow `release.yml`。如果改用 automation token，取消 release.yml 里 `NODE_AUTH_TOKEN` 的注释并添加同名 secret。
 
 项目结构：
 

package/client.js

@@ -126,6 +126,13 @@ window.__ModuleLoader__.load({
       corruptBanner: '回收站索引损坏，已进入保护模式。现有会话不会被自动修改。',
       recoveredBanner: '回收站索引已从备份恢复。',
       unindexedBanner: '回收站目录中有 {count} 个未索引对象，插件不会自动删除它们。',
+      orphansClean: '清理空目录',
+      orphansTitle: '清理空的无主对象？',
+      orphansBody: '只删除回收站中不含会话日志的残留目录；可能含日志的无主对象会保留。',
+      orphansConfirm: '清理空目录',
+      orphansDoneOne: '已清理 {count} 个空的无主对象',
+      orphansDoneOther: '已清理 {count} 个空的无主对象',
+      orphansNone: '没有可安全清理的空目录',
       rebuild: '尝试重建索引',
       rebuilding: '正在重建…',
       rebuildDone: '索引已重建，共 {count} 个条目',
@@ -281,6 +288,13 @@ window.__ModuleLoader__.load({
       corruptBanner: 'The trash index is damaged, so protection mode is on. No session is changed automatically.',
       recoveredBanner: 'The trash index was recovered from its backup.',
       unindexedBanner: 'The trash directory holds {count} unindexed objects. The plugin will not delete them.',
+      orphansClean: 'Clean empty leftovers',
+      orphansTitle: 'Remove empty unindexed objects?',
+      orphansBody: 'Only leftover directories without session logs are removed; unindexed objects that may contain logs are kept.',
+      orphansConfirm: 'Clean empty objects',
+      orphansDoneOne: 'Removed {count} empty unindexed object',
+      orphansDoneOther: 'Removed {count} empty unindexed objects',
+      orphansNone: 'No empty leftovers to clean',
       rebuild: 'Try rebuilding the index',
       rebuilding: 'Rebuilding…',
       rebuildDone: 'Index rebuilt with {count} entries',
@@ -889,8 +903,14 @@ window.__ModuleLoader__.load({
           if (wrapRef.current !== null && !wrapRef.current.contains(event.target)) setOpen(false)
         }
         const onKeyDown = (event) => {
+          if (event.key === 'Tab') {
+            // Let focus leave the menu naturally; just stop leaving it open.
+            setOpen(false)
+            return
+          }
           if (event.key !== 'Escape') return
           event.preventDefault()
+          event.stopPropagation()
           setOpen(false)
           if (buttonRef.current !== null) buttonRef.current.focus()
         }
@@ -992,9 +1012,11 @@ window.__ModuleLoader__.load({
               },
               items.map((item, index) =>
                 h(
-                  'div',
+                  React.Fragment,
                   { key: item.key },
-                  item.separatorBefore === true && index > 0 ? h('div', { className: 'dsh-trash__menuSeparator' }) : null,
+                  item.separatorBefore === true && index > 0
+                    ? h('div', { className: 'dsh-trash__menuSeparator', role: 'separator' })
+                    : null,
                   h(
                     'button',
                     {
@@ -1034,7 +1056,7 @@ window.__ModuleLoader__.load({
      * }} props dialog content and handlers.
      * @returns {import('react').ReactElement} the dialog overlay.
      */
-    function ConfirmDialog({ kind, entry, count, t, onCancel, onConfirm }) {
+    function ConfirmDialog({ kind, entry, count, t, onCancel, onConfirm, fallbackRef }) {
       const dialogRef = React.useRef(null)
       const cancelRef = React.useRef(null)
       const titleId = `dsh-trash-dialog-title-${kind}`
@@ -1068,7 +1090,12 @@ window.__ModuleLoader__.load({
         document.addEventListener('keydown', onKeyDown, true)
         return () => {
           document.removeEventListener('keydown', onKeyDown, true)
-          if (previous !== null && typeof previous.focus === 'function') previous.focus()
+          if (previous !== null && typeof previous.focus === 'function' && previous.isConnected !== false) {
+            previous.focus()
+            return
+          }
+          const fallback = fallbackRef === null || fallbackRef === undefined ? null : fallbackRef.current
+          if (fallback !== null && typeof fallback.focus === 'function') fallback.focus()
         }
       }, [onCancel])
 
@@ -1089,6 +1116,10 @@ window.__ModuleLoader__.load({
         heading = format(t('purgeAllTitle'), { count })
         body = t('purgeAllBody')
         confirmLabel = t('purgeAllConfirm')
+      } else if (kind === 'orphans') {
+        heading = t('orphansTitle')
+        body = t('orphansBody')
+        confirmLabel = t('orphansConfirm')
       } else {
         heading = t('forgetTitle')
         body = t('forgetBody')
@@ -1151,6 +1182,7 @@ window.__ModuleLoader__.load({
         const [cleaning, setCleaning] = React.useState(false)
         const [rebuilding, setRebuilding] = React.useState(false)
         const [purgingAll, setPurgingAll] = React.useState(false)
+        const [forgettingOrphans, setForgettingOrphans] = React.useState(false)
         const [announcement, setAnnouncement] = React.useState('')
         const [clock, setClock] = React.useState(() => Date.now())
         const [query, setQuery] = React.useState('')
@@ -1165,6 +1197,8 @@ window.__ModuleLoader__.load({
         const activeWritesRef = React.useRef(0)
         /** Abort scopes of in-flight writes, all cancelled on unmount. */
         const writeScopesRef = React.useRef(new Set())
+        /** The page-open sweep is requested once per mounted section. */
+        const pageSweepRef = React.useRef(false)
         const closeDialog = React.useCallback(() => setDialog(null), [])
 
         /**
@@ -1266,7 +1300,7 @@ window.__ModuleLoader__.load({
          *   | { kind: 'network' }
          * >} the outcome.
          */
-        async function sendMutation(pathname, body) {
+        async function sendMutationOnce(pathname, body) {
           const scope = openWriteScope()
           try {
             const { status, ok, payload } = await requestJson(pathname, { method: 'POST', body, signal: scope.signal })
@@ -1280,6 +1314,30 @@ window.__ModuleLoader__.load({
           }
         }
 
+        /**
+         * Send one write request. A LOCKED answer means the Host rejected the
+         * call before touching anything, so it is safe to retry once after a
+         * short jitter instead of surfacing a spurious failure.
+         *
+         * @param {string} pathname endpoint below the API prefix.
+         * @param {object} [body] JSON request body.
+         * @returns {Promise<any>} the outcome, see {@link sendMutationOnce}.
+         */
+        async function sendMutation(pathname, body) {
+          let outcome = await sendMutationOnce(pathname, body)
+          if (outcome.kind === 'response' && outcome.ok === false) {
+            const code =
+              outcome.payload !== null && outcome.payload !== undefined && outcome.payload.error !== undefined
+                ? outcome.payload.error.code
+                : undefined
+            if (code === 'LOCKED') {
+              await new Promise((resolve) => setTimeout(resolve, 350 + Math.floor(Math.random() * 350)))
+              outcome = await sendMutationOnce(pathname, body)
+            }
+          }
+          return outcome
+        }
+
         /**
          * @param {'timeout' | 'network'} kind transport failure.
          * @returns {string} the localized message to show.
@@ -1315,6 +1373,12 @@ window.__ModuleLoader__.load({
               }
               setView({ status: 'ready', data: payload, error: null })
               setRowErrors({})
+              // Read-only /state never deletes; ask the Host for the throttled
+              // maintenance sweep explicitly, once per mounted page.
+              if (!pageSweepRef.current) {
+                pageSweepRef.current = true
+                requestJson('sweep', { method: 'POST' }).catch(() => {})
+              }
             })
             .catch(() => {
               if (controller.signal.aborted) {
@@ -1402,7 +1466,8 @@ window.__ModuleLoader__.load({
         const loading = view.status === 'loading'
         const refreshing = view.status === 'refreshing'
         const readsBusy = loading || refreshing
-        const pendingCount = pendingRows.size + (cleaning ? 1 : 0) + (purgingAll ? 1 : 0) + (rebuilding ? 1 : 0)
+        const pendingCount =
+          pendingRows.size + (cleaning ? 1 : 0) + (purgingAll ? 1 : 0) + (rebuilding ? 1 : 0) + (forgettingOrphans ? 1 : 0)
         /** Any write (row action or maintenance) is in flight. */
         const mutationBusy = pendingCount > 0
         const corrupt = data !== null && data.index !== undefined && data.index.status === 'corrupt'
@@ -1745,6 +1810,39 @@ window.__ModuleLoader__.load({
           }
         }
 
+        /**
+         * Remove empty unindexed object directories. They contain no session
+         * log, only leftover plugin metadata, so this is safe to offer.
+         *
+         * @returns {Promise<void>} completion of the operation.
+         */
+        async function performPurgeOrphans() {
+          if (!beginWrite()) return
+          setForgettingOrphans(true)
+          try {
+            const outcome = await sendMutation('orphans/forget')
+            if (!aliveRef.current || outcome.kind === 'cancelled') return
+            if (outcome.kind !== 'response') {
+              ctx.contextMenus.notify(transportMessage(outcome.kind), false)
+              return
+            }
+            if (!outcome.ok) {
+              ctx.contextMenus.notify(describeActionFailure(outcome.status, outcome.payload, t), false)
+              return
+            }
+            const payload = outcome.payload
+            const removed =
+              payload !== null && payload !== undefined && typeof payload.removed === 'number' ? payload.removed : 0
+            const message = removed > 0 ? countText(t, 'orphansDone', removed) : t('orphansNone')
+            bumpRevision()
+            ctx.contextMenus.notify(message, removed > 0)
+            announce(message)
+          } finally {
+            endWrite()
+            if (aliveRef.current) setForgettingOrphans(false)
+          }
+        }
+
         /**
          * @param {object} entry wire entry.
          * @param {string} key menu identity.
@@ -1905,6 +2003,16 @@ window.__ModuleLoader__.load({
               'div',
               { className: 'dsh-trash__banner dsh-trash__banner--info', role: 'status', key: 'unindexed' },
               h('span', { className: 'dsh-trash__bannerText' }, format(t('unindexedBanner'), { count: unindexed })),
+              h(
+                'button',
+                {
+                  type: 'button',
+                  className: 'dsh-trash__button',
+                  onClick: () => setDialog({ kind: 'orphans' }),
+                  disabled: loading || mutationBusy,
+                },
+                t('orphansClean'),
+              ),
             ),
           )
         }
@@ -2269,6 +2377,7 @@ window.__ModuleLoader__.load({
                   className: 'dsh-trash__panel',
                   key: 'panel',
                   ref: panelRef,
+                  tabIndex: -1,
                   'aria-busy': readsBusy ? 'true' : 'false',
                 },
                 panelBody,
@@ -2289,12 +2398,14 @@ window.__ModuleLoader__.load({
                 count: dialog.count,
                 t,
                 onCancel: closeDialog,
+                fallbackRef: panelRef,
                 onConfirm: () => {
                   const current = dialog
                   setDialog(null)
                   if (current.kind === 'orphan') void performRestore(current.entry, 'orphan')
                   else if (current.kind === 'purge') void performPurge(current.entry)
                   else if (current.kind === 'purgeAll') void performPurgeAll()
+                  else if (current.kind === 'orphans') void performPurgeOrphans()
                   else void performForget(current.entry)
                 },
               })

package/index.js

@@ -34,7 +34,7 @@ function createLogger(ctx) {
   const prefix = 'dsh-session-trash'
   let sink = null
   try {
-    const factory = ctx.get('logger')
+    const factory = /** @type {any} */ (ctx.get('logger'))
     if (typeof factory === 'function') {
       const instance = factory(prefix)
       if (instance !== null && instance !== undefined && typeof instance.info === 'function') sink = instance
@@ -65,7 +65,7 @@ function createLogger(ctx) {
  * recovery, and the retention sweep.
  *
  * @param {import('@deepseek-ai/cordis').Context} ctx plugin context.
- * @param {object} config validated plugin configuration.
+ * @param {any} config validated plugin configuration.
  * @returns {void}
  */
 export function apply(ctx, config) {

package/lib/cleanup.js

@@ -14,7 +14,7 @@ export const CLEANUP_RETRY_MAX_MS = 60 * 60 * 1000
 const STOPPED_RESULT = Object.freeze({ purged: 0, failed: 0, settled: 0 })
 
 /**
- * @param {unknown} error arbitrary failure.
+ * @param {any} error arbitrary failure.
  * @returns {string} a concise message.
  */
 function messageOf(error) {
@@ -22,7 +22,7 @@ function messageOf(error) {
 }
 
 /**
- * @param {unknown} error arbitrary failure.
+ * @param {any} error arbitrary failure.
  * @returns {string} a bounded diagnostic message for `/state`.
  */
 function errorText(error) {
@@ -60,18 +60,18 @@ function resolveTimer(ctx) {
  *
  * @param {{
  *   ctx: import('@deepseek-ai/cordis').Context,
- *   trashService: { sweep: (options: { allowPurge: boolean, now: number, reason: string }) => Promise<object> },
+ *   trashService: { sweep: (options: { allowPurge: boolean, now: number, reason: string }) => Promise<any> },
  *   config: { sweepIntervalHours: number, enableAutoCleanup: boolean },
  *   logger: { info: Function, warn: Function, error: Function, debug: Function },
  * }} deps host services and the configured cadence.
  * @returns {{
  *   start: () => void,
  *   stop: () => void,
- *   runNow: (options?: { manual?: boolean, reason?: string }) => Promise<object>,
- *   maybeSweepOnPageOpen: () => void,
+ *   runNow: (options?: { manual?: boolean, reason?: string }) => Promise<any>,
+ *   sweepOnPageOpen: () => Promise<{ ran: boolean, reason?: string, result?: object }>,
  *   nextSweepAt: () => number | null,
  *   lastSweepAt: () => number,
- *   diagnostics: () => object,
+ *   diagnostics: () => any,
  * }} the cleanup service.
  */
 export function createCleanupService({ ctx, trashService, config, logger }) {
@@ -91,7 +91,7 @@ export function createCleanupService({ ctx, trashService, config, logger }) {
   let disposeRetry = null
 
   /**
-   * @param {unknown} error sweep failure.
+   * @param {any} error sweep failure.
    * @returns {void}
    */
   function report(error) {
@@ -148,7 +148,7 @@ export function createCleanupService({ ctx, trashService, config, logger }) {
    * because an automatic sweep may have been started with `allowPurge: false`.
    *
    * @param {{ manual?: boolean, reason?: string }} [options] manual trigger and diagnostic label.
-   * @returns {Promise<object>} the sweep summary.
+   * @returns {Promise<any>} the sweep summary.
    */
   async function runNow(options = {}) {
     if (stopped) return { ...STOPPED_RESULT }
@@ -294,17 +294,24 @@ export function createCleanupService({ ctx, trashService, config, logger }) {
     runNow,
 
     /**
-     * Trigger a throttled background sweep when the trash page opens. The
+     * Run the throttled sweep the trash page requests when it opens. The
      * timer-backed composition uses a one-hour throttle; without a timer the
-     * configured sweep interval throttles instead.
+     * configured sweep interval throttles instead. This is an explicit POST so
+     * the read-only `/state` projection never deletes anything.
      *
-     * @returns {void}
+     * @returns {Promise<{ ran: boolean, reason?: string, result?: object }>} the sweep outcome.
      */
-    maybeSweepOnPageOpen() {
-      if (stopped) return
+    async sweepOnPageOpen() {
+      if (stopped) return { ran: false, reason: 'stopped' }
       const throttle = timer === undefined || !config.enableAutoCleanup ? intervalMs : PAGE_OPEN_THROTTLE_MS
-      if (lastAttemptAt !== 0 && Date.now() - lastAttemptAt <= throttle) return
-      void runNow({ reason: 'page-open' }).catch(report)
+      if (lastAttemptAt !== 0 && Date.now() - lastAttemptAt <= throttle) return { ran: false, reason: 'throttled' }
+      try {
+        const result = await runNow({ reason: 'page-open' })
+        return { ran: true, result }
+      } catch (error) {
+        report(error)
+        return { ran: false, reason: 'failed' }
+      }
     },
 
     /**
@@ -324,7 +331,7 @@ export function createCleanupService({ ctx, trashService, config, logger }) {
     /**
      * Read-only cleanup diagnostics for `/state` and the settings page.
      *
-     * @returns {object} a JSON-safe diagnostic snapshot.
+     * @returns {any} a JSON-safe diagnostic snapshot.
      */
     diagnostics() {
       return {

package/lib/eligibility.js

@@ -7,14 +7,14 @@ export const PREFLIGHT_TTL_MS = 2000
 
 /**
  * @typedef {{ sessionId: string, header: object }} DescendantRef
- * @typedef {{ sessionId: string, header: object, location: { path: string }, formatStatus?: string }} PlannedMember
+ * @typedef {{ sessionId: string, header: any, location: { path: string }, formatStatus?: string }} PlannedMember
  * @typedef {{ eligible: true, members: PlannedMember[] } | { eligible: false, code: string, message: string, details?: object }} PreflightResult
  */
 
 /**
  * @param {string} code refusal code.
  * @param {string} message owner-facing explanation.
- * @param {object} [details] optional structured context.
+ * @param {any} [details] optional structured context.
  * @returns {{ eligible: false, code: string, message: string, details?: object }} a refusal.
  */
 function refuse(code, message, details) {
@@ -24,7 +24,7 @@ function refuse(code, message, details) {
 /**
  * Collect every stored session whose lineage descends from `sessionId`.
  *
- * @param {import('@deepseek-ai/dsh-session-persistence').SessionPersistence} persistence persistence service.
+ * @param {any} persistence persistence service.
  * @param {string} sessionId root session.
  * @returns {Promise<DescendantRef[]>} descendant identity and stored header.
  */
@@ -59,7 +59,7 @@ async function descendantsFromListing(persistence, sessionId) {
  * A grandchild whose direct parent is no longer stored still proves that the
  * root session owns a lineage the trash must not split.
  *
- * @param {readonly object[]} nodes descendant nodes from the trace.
+ * @param {readonly any[]} nodes descendant nodes from the trace.
  * @returns {DescendantRef[]} every descendant session identity and header.
  */
 function collectTraceDescendants(nodes) {
@@ -123,7 +123,7 @@ export function createEligibility({ ctx, store, logger }) {
 
   /**
    * @param {string} sessionId descendant session to validate.
-   * @returns {Promise<object>} either `{ member }` with the planned member or `{ refusal }`.
+   * @returns {Promise<any>} either `{ member }` with the planned member or `{ refusal }`.
    */
   async function planDescendant(sessionId) {
     let snapshot