@wangxiaocuo/dsh-session-trash 0.6.4 → 0.6.5

package/CHANGELOG.md

@@ -4,6 +4,24 @@
 
 ## [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
@@ -94,6 +112,7 @@
 
 - 回收站工具栏的「永久删除全部」与二次确认；`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

package/README.en.md

@@ -1,5 +1,7 @@
 # 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)
@@ -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,11 +169,12 @@ 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 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
 
@@ -177,6 +182,7 @@ The index schema is v2; a v1 index is upgraded automatically on startup and pres
 pnpm install
 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 (desktop app or npm-installed DSH)
 ```
@@ -189,11 +195,20 @@ What CI verifies:
 |---|---|
 | Unit tests, Host smoke test | CI: Ubuntu Node 20/22, Windows Node 22 |
 | Package contents (`npm pack`) | CI: Ubuntu |
+| 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.
+
+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:
 
 ```text

package/README.md

@@ -1,5 +1,7 @@
 # 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)
@@ -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,11 +168,12 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 - 孤儿恢复不会重建原工作区目录，也不会重新挂到工作区。
 - 归档和置顶状态会跨回收、恢复保留，回收站页面不管理这两个集合。
 - 永久删除只删除会话日志。附件、图片、投影缓存和搜索索引不会被删除。
+- 无主对象（`meta.json` 损坏或无法识别的对象目录）不会自动删除；页面只能清理其中不含会话日志的空目录，可能含日志的需要人工处理。
 - `/state` 一次返回全部条目摘要，页面在客户端搜索、筛选和分页。
 - 没有跨窗口实时推送。另一个窗口的变更要等刷新或窗口重新获得焦点后出现。
 - 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 分钟后，锁可能被另一个进程接管。
 
 ## 开发
 
@@ -176,6 +181,7 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 pnpm install
 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 安装的 DSH）
 ```
@@ -188,11 +194,20 @@ Host 冒烟测试通过 `@deepseek-ai/cordis` 这个 devDependency 装配真实
 |---|---|
 | 单元测试、Host 冒烟测试 | CI：Ubuntu Node 20/22、Windows Node 22 |
 | 打包内容（`npm pack`） | CI：Ubuntu |
+| 覆盖率门槛（`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 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。
+
 项目结构：
 
 ```text

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',
@@ -1102,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')
@@ -1164,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('')
@@ -1178,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), [])
 
         /**
@@ -1279,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 })
@@ -1293,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.
@@ -1328,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) {
@@ -1415,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'
@@ -1758,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.
@@ -1918,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'),
+              ),
             ),
           )
         }
@@ -2310,6 +2405,7 @@ window.__ModuleLoader__.load({
                   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/lib/cleanup.js

@@ -68,7 +68,7 @@ function resolveTimer(ctx) {
  *   start: () => void,
  *   stop: () => void,
  *   runNow: (options?: { manual?: boolean, reason?: string }) => Promise<any>,
- *   maybeSweepOnPageOpen: () => void,
+ *   sweepOnPageOpen: () => Promise<{ ran: boolean, reason?: string, result?: object }>,
  *   nextSweepAt: () => number | null,
  *   lastSweepAt: () => number,
  *   diagnostics: () => any,
@@ -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' }
+      }
     },
 
     /**

package/lib/errors.js

@@ -43,7 +43,7 @@ export class TrashError extends Error {
   /**
    * @param {string} code stable error code.
    * @param {string} message owner-facing explanation.
-   * @param {any} [details] optional structured context.
+   * @param {Record<string, unknown>} [details] optional structured context.
    */
   constructor(code, message, details) {
     super(message)
@@ -54,7 +54,7 @@ export class TrashError extends Error {
 }
 
 /**
- * @param {any} error arbitrary thrown value.
+ * @param {unknown} error arbitrary thrown value.
  * @returns {number} HTTP status for this error.
  */
 export function statusOf(error) {
@@ -86,26 +86,29 @@ const SAFE_DETAIL_KEYS = new Set([
  * Metrics snapshots are the only nested detail value the Host returns; keep
  * only their numeric counters so no path can ride along.
  *
- * @param {any} value candidate metrics object.
- * @returns {any | undefined} the numeric metrics.
+ * @param {unknown} value candidate metrics object.
+ * @returns {{ sizeBytes?: number, fileCount?: number, symlinkCount?: number } | undefined} the numeric metrics.
  */
 function sanitizeMetrics(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const record = /** @type {Record<string, unknown>} */ (value)
+  /** @type {Record<string, unknown>} */
   const safe = {}
   for (const key of ['sizeBytes', 'fileCount', 'symlinkCount']) {
-    if (typeof value[key] === 'number') safe[key] = value[key]
+    if (typeof record[key] === 'number') safe[key] = record[key]
   }
   return Object.keys(safe).length === 0 ? undefined : safe
 }
 
 /**
- * @param {any} details arbitrary structured context.
- * @returns {any | undefined} the same context restricted to whitelisted keys.
+ * @param {unknown} details arbitrary structured context.
+ * @returns {Record<string, unknown> | undefined} the same context restricted to whitelisted keys.
  */
 export function sanitizeDetails(details) {
   if (details === null || typeof details !== 'object' || Array.isArray(details)) return undefined
+  /** @type {Record<string, unknown>} */
   const safe = {}
-  for (const [key, value] of Object.entries(details)) {
+  for (const [key, value] of Object.entries(/** @type {Record<string, unknown>} */ (details))) {
     if (!SAFE_DETAIL_KEYS.has(key)) continue
     if (key === 'expected' || key === 'measured') {
       const metrics = sanitizeMetrics(value)
@@ -122,8 +125,8 @@ export function sanitizeDetails(details) {
 }
 
 /**
- * @param {any} error arbitrary thrown value.
- * @returns {{ code: string, message: string, details?: object }} the wire error shape.
+ * @param {unknown} error arbitrary thrown value.
+ * @returns {{ code: string, message: string, details?: Record<string, unknown> }} the wire error shape.
  */
 export function toWireError(error) {
   if (error instanceof TrashError) {

package/lib/fsops.js

@@ -36,11 +36,13 @@ const COPY_OPTIONS = {
 }
 
 /**
- * @param {any} error thrown filesystem failure.
+ * @param {unknown} error thrown filesystem failure.
  * @returns {string | undefined} the Node error code.
  */
 export function errorCode(error) {
-  return error !== null && typeof error === 'object' && typeof error.code === 'string' ? error.code : undefined
+  if (error === null || typeof error !== 'object') return undefined
+  const code = /** @type {Record<string, unknown>} */ (error).code
+  return typeof code === 'string' ? code : undefined
 }
 
 /**
@@ -194,7 +196,7 @@ export function isInside(root, target) {
 }
 
 /**
- * @param {any} trashId candidate object identity.
+ * @param {unknown} trashId candidate object identity.
  * @returns {boolean} whether the identity is one safe path segment.
  */
 export function isSafeTrashId(trashId) {
@@ -214,7 +216,7 @@ export function isSafeTrashId(trashId) {
  * object. Session ids are `session-<uuid>` or a bare uuid today, so the
  * accepted alphabet is deliberately conservative.
  *
- * @param {any} sessionId candidate member identity.
+ * @param {unknown} sessionId candidate member identity.
  * @returns {boolean} whether the identity is one safe path segment.
  */
 export function isSafeMemberId(sessionId) {
@@ -339,7 +341,7 @@ export function createTrashId() {
  * @param {string} destination final directory path.
  * @param {{ sizeBytes: number, fileCount: number }} expected recorded metrics.
  * @param {(from: string, to: string) => Promise<void>} rename rename implementation for tests.
- * @param {(source: string, destination: string, options: any) => Promise<void>} copy copy implementation for tests.
+ * @param {(source: string, destination: string, options: import('node:fs').CopyOptions) => Promise<void>} copy copy implementation for tests.
  * @returns {Promise<void>} resolution after the destination is published.
  */
 async function copyAcrossDevices(source, destination, expected, rename, copy) {
@@ -382,7 +384,7 @@ async function copyAcrossDevices(source, destination, expected, rename, copy) {
  * @param {{
  *   logger?: { warn: Function },
  *   rename?: (from: string, to: string) => Promise<void>,
- *   copy?: (source: string, destination: string, options: any) => Promise<void>,
+ *   copy?: (source: string, destination: string, options: import('node:fs').CopyOptions) => Promise<void>,
  * }} [options] diagnostics sink and test seams.
  * @returns {Promise<void>} resolution after the directory lives at `destination`.
  */

package/lib/http.js

@@ -160,12 +160,13 @@ function requireSessionId(body) {
  *     forget: (sessionId: string) => Promise<any>,
  *     reveal: (sessionId: string, signal?: AbortSignal) => Promise<any>,
  *     rebuild: () => Promise<any>,
+ *     purgeEmptyOrphans: () => Promise<{ removed: number }>,
  *   },
  *   cleanupService?: {
-    runNow: (options?: any) => Promise<any>,
-    maybeSweepOnPageOpen: () => void,
-    diagnostics?: () => any,
-  },
+ *     runNow: (options?: any) => Promise<any>,
+ *     sweepOnPageOpen: () => Promise<{ ran: boolean, reason?: string, result?: any }>,
+ *     diagnostics?: () => any,
+ *   },
  *   ready: Promise<unknown>,
  *   config: any,
  *   logger: any,
@@ -264,11 +265,28 @@ export function registerApi({ ctx, eligibility, stateService, trashService, clea
 
   route('state', 'GET', async (_req, res) => {
     sendJson(res, 200, await stateService.snapshot())
-    try {
-      cleanupService?.maybeSweepOnPageOpen()
-    } catch (error) {
-      logger.warn(`cannot schedule the page-open trash sweep: ${error instanceof Error ? error.message : String(error)}`)
-    }
+  })
+
+  route('sweep', 'POST', async (_req, res) => {
+    const outcome = await cleanupService.sweepOnPageOpen()
+    const result = outcome.result !== null && outcome.result !== undefined ? outcome.result : null
+    sendJson(res, 200, {
+      ok: true,
+      ran: outcome.ran === true,
+      ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+      ...(result === null
+        ? {}
+        : {
+            purged: result.purged ?? 0,
+            failed: result.failed ?? 0,
+            settled: result.changed ?? 0,
+          }),
+    })
+  })
+
+  route('orphans/forget', 'POST', async (_req, res) => {
+    const result = await trashService.purgeEmptyOrphans()
+    sendJson(res, 200, { ok: true, removed: result.removed ?? 0 })
   })
 
   route('preflight', 'POST', async (req, res) => {

package/lib/inventory.js

@@ -336,6 +336,30 @@ export async function scanObjects(store, logger) {
   return { objects, unindexed }
 }
 
+/**
+ * Plugin-owned sidecar names that may remain inside an otherwise empty object
+ * directory. Everything else (session/, children/, stray files) is payload.
+ */
+const PLUGIN_OWNED_OBJECT_NAMES = new Set(['meta.json', 'meta.json.tmp'])
+
+/**
+ * Whether an object directory holds no session payload, only plugin metadata
+ * that can be recreated. Used to offer a safe cleanup for unindexed leftovers.
+ *
+ * @param {import('./store.js').TrashStore} store trash store owning `objects/`.
+ * @param {string} trashId object identity.
+ * @returns {Promise<boolean>} whether the directory is safe to remove.
+ */
+export async function isEmptyObjectDir(store, trashId) {
+  if (!isSafeTrashId(trashId)) return false
+  try {
+    const names = await fs.readdir(store.objectDir(trashId))
+    return names.every((name) => PLUGIN_OWNED_OBJECT_NAMES.has(name))
+  } catch {
+    return false
+  }
+}
+
 /**
  * Import object directories the index does not know about and mark entries
  * whose object directory vanished. Never deletes a session file or an object

package/lib/store.js

@@ -14,6 +14,22 @@ export const LOCK_STALE_MS = 10 * 60 * 1000
 /** How often a long-running operation refreshes its lock heartbeat. */
 export const LOCK_REFRESH_MS = 60 * 1000
 
+/** How many times a caller retries a lock held by another live process. */
+export const LOCK_WAIT_ATTEMPTS = 3
+
+/** Base delay between live-lock retries. */
+export const LOCK_WAIT_DELAY_MS = 200
+
+/**
+ * @param {number} milliseconds delay length.
+ * @returns {Promise<void>} resolution after the delay.
+ */
+function sleep(milliseconds) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, milliseconds)
+  })
+}
+
 /**
  * @param {number} [now] timestamp for the new index.
  * @returns {{ version: number, updatedAt: number, entries: any[] }} an empty index document.
@@ -558,10 +574,15 @@ export class TrashStore {
   }
 
   /**
+   * Acquire the cross-process lock. A lock held by another live process is
+   * retried for a short window first, so two windows clicking at the same time
+   * do not surface a spurious LOCKED error.
+   *
    * @returns {Promise<void>} resolution once this process owns the lock.
    */
   async acquireLock() {
-    for (let attempt = 0; attempt < 3; attempt += 1) {
+    let waits = 0
+    for (let attempt = 0; attempt < 6; attempt += 1) {
       try {
         const handle = await fs.open(this.lockPath, 'wx', 0o600)
         try {
@@ -576,6 +597,11 @@ export class TrashStore {
           throw new TrashError('IO_ERROR', `Cannot create the trash lock: ${error instanceof Error ? error.message : String(error)}`)
         }
         if (!(await this.lockIsStale())) {
+          if (waits < LOCK_WAIT_ATTEMPTS - 1) {
+            waits += 1
+            await sleep(LOCK_WAIT_DELAY_MS * waits)
+            continue
+          }
           throw new TrashError('LOCKED', 'Another trash operation is in progress. Try again in a moment.')
         }
         try {

package/lib/trash-service.js

@@ -14,7 +14,7 @@ import {
   samePath,
 } from './fsops.js'
 import { mapLimit } from './concurrency.js'
-import { reconcileIndex, rebuildIndex, memberPresence } from './inventory.js'
+import { isEmptyObjectDir, memberPresence, rebuildIndex, reconcileIndex, scanObjects } from './inventory.js'
 import { aggregateMetrics, memberList } from './members.js'
 
 /** How many short retries confirm a moved or restored session is visible. */
@@ -1011,15 +1011,17 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
    */
   async function trash(sessionId) {
     const startedAt = Date.now()
+    // Lineage listing and live checks are slow; resolve them before taking the
+    // cross-process lock and keep only the directory re-checks inside it.
+    eligibility.invalidate(sessionId)
+    const verdict = await eligibility.evaluate(sessionId)
+    if (verdict.eligible !== true) {
+      throw new TrashError(verdict.code, verdict.message, verdict.details)
+    }
     return store.withLock(async () => {
       if (store.isProtected()) {
         throw new TrashError('INDEX_CORRUPT', 'The trash index is unreadable, so protection mode refuses new entries.')
       }
-      eligibility.invalidate(sessionId)
-      const verdict = await eligibility.evaluate(sessionId)
-      if (verdict.eligible !== true) {
-        throw new TrashError(verdict.code, verdict.message, verdict.details)
-      }
       const existing = store.findEntry(sessionId)
       if (existing !== undefined) {
         if (existing.state === 'missing') {
@@ -1520,6 +1522,40 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
     })
   }
 
+  /**
+   * Remove unindexed object directories that contain no session payload, only
+   * plugin metadata. Directories that may still hold session logs are kept for
+   * manual inspection.
+   *
+   * @returns {Promise<{ removed: number }>} how many empty object directories were removed.
+   */
+  async function purgeEmptyOrphans() {
+    return store.withLock(async () => {
+      if (store.isProtected()) {
+        throw new TrashError('INDEX_CORRUPT', 'The trash index is unreadable, so protection mode refuses changes.')
+      }
+      const { objects } = await scanObjects(store, logger)
+      const indexed = new Set(store.entries().map((entry) => entry.trashId))
+      let removed = 0
+      for (const object of objects) {
+        if (indexed.has(object.trashId)) continue
+        if (!(await isEmptyObjectDir(store, object.trashId))) continue
+        try {
+          await store.removeObjectDir(object.trashId)
+          removed += 1
+          logger.info(`removed an empty unindexed trash object (${object.trashId})`)
+        } catch (error) {
+          logger.warn(`cannot remove empty unindexed trash object ${object.trashId}: ${messageOf(error)}`)
+        }
+      }
+      if (removed > 0) {
+        const { unindexed } = await scanObjects(store, logger)
+        store.unindexed = unindexed
+      }
+      return { removed }
+    })
+  }
+
   /**
    * Restore the index from object sidecars after the primary index and its
    * backup were both rejected.
@@ -1741,5 +1777,5 @@ export function createTrashService({ ctx, store, eligibility, config, logger, pa
     return summary
   }
 
-  return { trash, restore, recover, purge, purgeAll, forget, sweep, rebuild, reveal }
+  return { trash, restore, recover, purge, purgeAll, forget, sweep, rebuild, reveal, purgeEmptyOrphans }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangxiaocuo/dsh-session-trash",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "DeepSeek Harness plugin: move cold sessions into a recoverable trash, restore them within the retention window, or delete their logs permanently.",
   "license": "MIT",
   "author": "wangxiaocuo",