dsh-archived-chats 1.4.6 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@
 
 Entries describe behavior at each release, not necessarily current behavior. Consult the READMEs and user guides for current usage.
 
+## 1.5.0 — 2026-10-08
+
+### 中文
+
+- 永久删除、清空回收站及重启重试一并清理子代理后代，保留独立分叉；删除目标持久化，活动代理先停止，失败可重试（#57）。
+- 新增「未归档」视图，复用已归档的工作区分组排版；搜索在顶部，筛选行右侧提供刷新图标。会话行提供只读预览图标，支持单条归档、工作区全部归档及全局全部归档，归档均先确认；搜索和筛选不缩小批量范围。
+- 修复弹窗、对话预览顶栏、菜单及成功提示的背景穿透，使用随明暗主题变化的不透明宿主层。
+- 修复下载中断后的导出流释放，以及部分删除后的回收站和侧栏刷新。
+- 在「空间与策略」新增按需残留会话检查：仅处理明确缺父的子代理，提供完整 ID、搜索多选、只读预览、备份及确认删除。超限先询问，删除与重启重试只处理选中项（#58）。
+
+### English
+
+- Cascade permanent deletion and recovery through subagent descendants while preserving forks and independent recycle records. Persist targets before removal and quiesce live agents (#57).
+- Add Unarchived using Archived’s workspace-group layout, with search above filters and a refresh icon at the right. Offer read-only chat previews and confirmed individual, workspace-wide, and global archiving; search and filters do not narrow bulk scope.
+- Fix transparent dialog, preview-header, menu, and success-toast backgrounds with opaque Host surfaces that follow light and dark themes.
+- Release interrupted export streams and refresh the sidebar and recycle list after partial deletion.
+- Add an on-demand residual check in Storage & Retention for subagents with confirmed missing parents: full IDs, search, selection, read-only previews, backups and confirmed deletion. Ask before excluding oversized backups; delete and retry only selected records (#58).
+
 ## 1.4.6 — 2026-10-02
 
 ### 中文

package/README.md

@@ -32,7 +32,7 @@ Archive Management gives DeepSeek Harness a place to find chats hidden from the
 
 > The English name is **Archive Management**, and the Chinese name is **归档管理**. The installation package remains `dsh-archived-chats`.
 >
-> This document follows the `main` branch and targets 1.4.6. This release fixes permanent deletion and Recycle Bin cleanup when historical and current session log generations coexist. See the [changelog](CHANGELOG.md) for release history.
+> This document follows the `main` branch and targets 1.5.0. This release adds Unarchived management and on-demand residual chat checks, and fixes subagent cascade deletion and overlay backgrounds. See the [changelog](CHANGELOG.md) for release history.
 
 ## Quick start
 
@@ -57,14 +57,15 @@ dsh plugin --profile web update dsh-archived-chats
 | Area | Current behavior |
 | --- | --- |
 | Browse and search | Workspace-grouped archived chats, full-text search, filters, sorting, tags, and notes. |
-| Workspace archiving | A settings-owned workspace chooser supports one or more workspaces and one aggregate confirmation; blank, active, or unreadable chats are skipped. |
+| Workspace archiving | Unarchived offers individual, workspace-wide, and global archiving with aggregate confirmation; blank, active, or unreadable chats are skipped. |
 | Read-only preview | Conversations, reasoning, tool activity, Markdown, JSON, code, and readable stored images without unarchiving. |
 | Backup | Export one workspace or the entire archive as JSON + Markdown ZIP; preview imports and skip conflicting IDs. |
 | Recycle Bin | Move archived chats by workspace; restore one chat, a workspace, or the entire Recycle Bin back to Archived. |
 | Permanent deletion | Delete one archived chat, a workspace's archive, or all archived chats after confirmation. Recycle Bin deletion is separate. |
+| Residual chat check | Start a manual check in Storage & Retention for subagents whose parent no longer exists; search, select, preview, back up and confirm permanent deletion of selected records only. Empty chats are excluded. |
 | Storage and relationships | Storage accounting, optional automatic Recycle Bin cleanup, and read-only Origins & Branches. |
 
-The five views are **Archived**, **Recycle Bin**, **Storage & Retention**, **Origins & Branches**, and **About**. Archiving does not create historical versions; Recycle Bin protection snapshots support recovery, not a browsable version-history library.
+The six views are **Archived**, **Unarchived**, **Recycle Bin**, **Storage & Retention**, **Origins & Branches**, and **About**. Unarchived shares Archived’s search, filters, and workspace-group layout, offering read-only chat previews and individual, workspace-wide, and global archiving. Archiving does not create historical versions; Recycle Bin protection snapshots support recovery, not a browsable version-history library.
 
 ## Screenshots
 
@@ -72,14 +73,14 @@ These screenshots show the current interface with synthetic example chats; they
 
 1. [Archived chats](assets/screenshots/preview-01.png)
 2. [Full-text search](assets/screenshots/preview-02.png)
-3. [Workspace bulk archive](assets/screenshots/preview-03.png)
+3. [Unarchived and workspace archiving](assets/screenshots/preview-03.png)
 4. [Read-only preview](assets/screenshots/preview-04.png)
 5. [Recycle Bin](assets/screenshots/preview-05.png)
 6. [Restore confirmation](assets/screenshots/preview-06.png)
 7. [Storage & Retention](assets/screenshots/preview-07.png)
 8. [Origins & Branches](assets/screenshots/preview-08.png)
 
-The Archived header has **Bulk archive** and **More**. More contains Import backup, Export all, Unarchive all, then Delete all after a separator. The Recycle Bin header directly shows **Restore all** and **Empty Recycle Bin** without a More menu. Recycle rows retain the preview icon and use compact **Restore** and **Delete** text buttons. Workspace and global restoration separately confirm scope, counts, and the Archived destination, skipping pending deletions. Empty Recycle Bin still requires irreversible-action confirmation. The header keeps consistent dimensions across tabs. Workspace actions and global export, unarchive, and deletion ask you to confirm the complete archive scope and chat count.
+The Archived header has **More**. More contains Import backup, Export all, Unarchive all, then Delete all after a separator. The Recycle Bin header directly shows **Restore all** and **Empty Recycle Bin** without a More menu. Recycle rows retain the preview icon and use compact **Restore** and **Delete** text buttons. Workspace and global restoration separately confirm scope, counts, and the Archived destination, skipping pending deletions. Empty Recycle Bin still requires irreversible-action confirmation. The header keeps consistent dimensions across tabs. Workspace actions and global export, unarchive, and deletion ask you to confirm the complete archive scope and chat count.
 
 **About** shows the running version, author, license, guides, project and feedback links, and Check for updates. Opening the page checks public npm version metadata in the background, at most once every 12 hours during a running backend session; failures never block archive management. A newer version adds a **Get update** link beside the title, opening the plugin market without installing or restarting anything. Follow the host's restart guidance when convenient; a browser refresh alone may not load an updated backend. No chat or backup content is sent during update checks.
 
@@ -134,7 +135,7 @@ The package declares DSH `>=0.1.0-rc.7`; individual features depend on public Ho
 
 Recycle Bin preview still depends on the original session; a missing original may prevent preview even when a protection snapshot can restore it. See [compatibility and limits](docs/USER_GUIDE.md#compatibility-and-limits).
 
-The declared range remains capability-based. Release automation tests Node.js 18 on Ubuntu and Node.js 24 on Ubuntu, macOS, and Windows; the Node.js 24 matrix requires the official `@deepseek-ai/dsh-session@0.1.7-rc.2` Host backend integration (6/6) and package checks, including the v4 session format.
+The declared range remains capability-based. Release automation tests Node.js 18 on Ubuntu and Node.js 24 on Ubuntu, macOS, and Windows; the Node.js 24 matrix requires the official `@deepseek-ai/dsh-session@0.1.7-rc.2` Host backend integration (7/7) and package checks, including the v4 session format.
 
 ## Documentation
 
@@ -159,7 +160,7 @@ node scripts/run-native-integration.mjs
 npm pack --dry-run --json
 ```
 
-The suite covers Host and browser behavior, export/import, snapshot fallback recovery, Recycle Bin, retention, search, responsive layout, public types, package contents, and repository hygiene. The native commands install the locked `@deepseek-ai/dsh-session@0.1.7-rc.2` fixture and require all six native integration cases to run without skips. All checks use isolated temporary data and never read real sessions.
+The suite covers Host and browser behavior, export/import, snapshot fallback recovery, Recycle Bin, retention, search, responsive layout, public types, package contents, and repository hygiene. The native commands install the locked `@deepseek-ai/dsh-session@0.1.7-rc.2` fixture and require all seven native integration cases to run without skips. All checks use isolated temporary data and never read real sessions.
 
 ## Uninstall
 

package/README.zh-CN.md

@@ -30,7 +30,7 @@
 
 > 中文名称为「归档管理」，英文名称为 Archive Management；安装包名始终为 `dsh-archived-chats`。
 >
-> 本文跟随 `main` 分支维护，适用于 1.4.6。本版修复旧版与当前版本会话日志混存时，永久删除及回收站清空失败的问题。版本变更见[更新日志](CHANGELOG.md)。
+> 本文跟随 `main` 分支维护，适用于 1.5.0。本版新增未归档管理和按需残留会话检查，修复子代理级联删除与浮层背景。版本变更见[更新日志](CHANGELOG.md)。
 
 ## 快速开始
 
@@ -55,14 +55,15 @@ dsh plugin --profile web update dsh-archived-chats
 | 范围 | 当前行为 |
 | --- | --- |
 | 浏览与搜索 | 按工作区浏览归档聊天，支持全文搜索、筛选、排序、标签与备注。 |
-| 工作区批量归档 | 设置页的工作区选择器支持选择一个或多个工作区，汇总确认后归档；跳过空白、正在使用或无法确认内容的聊天。 |
+| 工作区批量归档 | 未归档视图支持单条、工作区和全局归档，汇总确认后执行；跳过空白、正在使用或无法确认内容的聊天。 |
 | 只读预览 | 无需取消归档即可查看对话、思考、工具活动、Markdown、JSON、代码及可读取的已存储图片。 |
 | 备份 | 支持按工作区或全部归档导出 JSON + Markdown ZIP；导入先预览，跳过冲突 ID。 |
 | 回收站 | 按工作区移入回收站；支持单条、工作区和整个回收站恢复到已归档。 |
 | 永久删除 | 确认后删除单条归档、工作区归档或全部归档；回收站删除独立操作。 |
+| 残留会话检查 | 空间与策略中手动检查父会话已不存在的子代理，支持明细搜索、多选、预览、备份及确认后永久删除；只删除选中项，不清理空会话。 |
 | 空间与关系 | 空间分账、可选的回收站自动清理，以及只读「来源与分支」。 |
 
-五个视图为 **已归档**、**回收站**、**空间与策略**、**来源与分支** 和 **关于**。归档不会创建历史版本；回收站保护快照仅用于恢复，不是可浏览的历史版本库。
+六个视图为 **已归档**、**未归档**、**回收站**、**空间与策略**、**来源与分支** 和 **关于**。未归档复用已归档的搜索、筛选和工作区分组排版，提供只读预览、单条归档、工作区全部归档和全局全部归档。归档不会创建历史版本；回收站保护快照仅用于恢复，不是可浏览的历史版本库。
 
 ## 界面截图
 
@@ -70,14 +71,14 @@ dsh plugin --profile web update dsh-archived-chats
 
 1. [已归档聊天](assets/screenshots/preview-01.png)
 2. [全文搜索](assets/screenshots/preview-02.png)
-3. [工作区批量归档](assets/screenshots/preview-03.png)
+3. [未归档与工作区归档](assets/screenshots/preview-03.png)
 4. [只读预览](assets/screenshots/preview-04.png)
 5. [回收站](assets/screenshots/preview-05.png)
 6. [恢复确认](assets/screenshots/preview-06.png)
 7. [空间与策略](assets/screenshots/preview-07.png)
 8. [来源与分支](assets/screenshots/preview-08.png)
 
-已归档页顶部仅保留 **批量归档** 和 **更多**；「更多」依次提供导入备份、全部导出、全部取消归档，分隔线后为全部删除。回收站顶部直接并列显示 **全部恢复** 和 **清空回收站**，不再设更多菜单；聊天行保留预览图标，使用紧凑的 **恢复** 和 **删除** 文字按钮。工作区恢复和全局恢复分别确认范围、数量及已归档去向，跳过正在永久删除的条目；清空仍须确认不可恢复的后果。各 Tab 顶部保持一致尺寸。工作区操作及全局导出、取消归档、删除均先确认完整归档范围和聊天数量。
+已归档页顶部保留 **更多**；未归档页顶部提供 **全部归档**，筛选行最右侧提供刷新图标；「更多」依次提供导入备份、全部导出、全部取消归档，分隔线后为全部删除。回收站顶部直接并列显示 **全部恢复** 和 **清空回收站**，不再设更多菜单；聊天行保留预览图标，使用紧凑的 **恢复** 和 **删除** 文字按钮。工作区恢复和全局恢复分别确认范围、数量及已归档去向，跳过正在永久删除的条目；清空仍须确认不可恢复的后果。各 Tab 顶部保持一致尺寸。工作区操作及全局导出、取消归档、删除均先确认完整归档范围和聊天数量。
 
 「关于」展示当前运行版本、作者、许可证、指南、项目与反馈链接，提供「检查更新」。打开页面时后台查询公开 npm 版本信息，运行期间自动检查间隔至少 12 小时；失败不会阻断归档功能。有新版时标题旁显示「去更新」，打开插件市场，不自动安装或重启。更新后按宿主提示自行安排重启 DSH，仅刷新网页不一定能加载新版后端。
 
@@ -132,7 +133,7 @@ dsh plugin --profile web update dsh-archived-chats
 
 回收站预览目前仍依赖原会话；原件丢失时，即使保护快照可恢复，也可能无法预览。详见[兼容性与限制](docs/USER_GUIDE.zh-CN.md#兼容性与限制)。
 
-声明的版本范围仍以 Host 公开能力为准。发布自动化在 Ubuntu 上测试 Node.js 18，并在 Ubuntu、macOS 和 Windows 上测试 Node.js 24；Node.js 24 矩阵强制运行基于官方 `@deepseek-ai/dsh-session@0.1.7-rc.2` 的 Host 后端集成（6/6）与打包检查，覆盖 v4 会话格式。
+声明的版本范围仍以 Host 公开能力为准。发布自动化在 Ubuntu 上测试 Node.js 18，并在 Ubuntu、macOS 和 Windows 上测试 Node.js 24；Node.js 24 矩阵强制运行基于官方 `@deepseek-ai/dsh-session@0.1.7-rc.2` 的 Host 后端集成（7/7）与打包检查，覆盖 v4 会话格式。
 
 ## 文档
 

package/docs/ARCHITECTURE.en.md

@@ -2,7 +2,7 @@
 
 English · [中文](ARCHITECTURE.md) · [User guide](USER_GUIDE.md)
 
-This document follows `main` and covers 1.4.6 behavior. This release fixes permanent deletion and Recycle Bin cleanup when historical and current session log generations coexist. See the [changelog](../CHANGELOG.md) for release history. Runtime code is the authority for interfaces and behavior; user-facing documentation should agree with it.
+This document follows `main` and covers 1.5.0 behavior. This release adds Unarchived management and on-demand residual chat checks, and fixes subagent cascade deletion and overlay backgrounds. See the [changelog](../CHANGELOG.md) for release history. Runtime code is the authority for interfaces and behavior; user-facing documentation should agree with it.
 
 ## Product boundary and modules
 
@@ -11,7 +11,7 @@ The plugin supplements archive management; it does not replace DSH's main chat a
 | Module (under `lib/`) | Responsibility |
 | --- | --- |
 | `index.js` | Host capability resolution, routes, archive visibility, lifecycle queue, physical deletion |
-| `client.js` | Settings page, five views, dialogs, native archive notice, request state |
+| `client.js` | Settings page, six views, dialogs, native archive notice, request state |
 | `about.js` | Local plugin identity, bounded public version checks, in-memory cache |
 | `persistence-compat.js` | Legacy inspect and modern read-handle adaptation; separate title reads |
 | `workspace-bulk-archive.js` | Eligible workspace chats, short-lived confirmation, apply-time checks |
@@ -21,6 +21,7 @@ The plugin supplements archive management; it does not replace DSH's main chat a
 | `search.js`, `stats.js`, `insights.js` | Message projection/search, directory measurements, storage accounting |
 | `retention.js`, `retention-service.js`, `auto-retention.js` | Policy, confirmation/revalidation, startup recovery and scheduling |
 | `lineage.js` | Read-only source, fork, and subagent projection |
+| `session-graph.js` | Session-id normalization, subagent descendant resolution, orphan classification |
 
 The UI moves chats to the Recycle Bin only through workspace actions. Rows can permanently delete or unarchive. Workspace export and export-all remain. A compatibility backend endpoint accepting one ID does not imply a row-level recycle action.
 
@@ -57,6 +58,11 @@ POST /plugins/dsh-archived-chats/unarchive
 POST /plugins/dsh-archived-chats/unarchive-all
 POST /plugins/dsh-archived-chats/delete
 POST /plugins/dsh-archived-chats/delete-all
+GET  /plugins/dsh-archived-chats/unarchived
+POST /plugins/dsh-archived-chats/unarchived/export
+GET  /plugins/dsh-archived-chats/orphans
+POST /plugins/dsh-archived-chats/orphans/delete
+POST /plugins/dsh-archived-chats/orphans/export
 ```
 
 Except for export, these POST routes require `x-dsh-archived-chats: 1`. Content preview, images, and search also use guarded POST. Export separately accepts a bounded native form without this header guard and checks current archive visibility for the requested sessions. Other routes parse their respective bounded payloads.
@@ -67,6 +73,12 @@ All `/history` and `/history/*` routes are removed; their former 410 response is
 
 Recycle endpoints call `restore`, `purge`, and `empty`. Empty requires the exact `trashed`/`degraded` record incarnations captured by the confirmation, including recycle and snapshot identity. The service purges only those targets: later records are excluded, and changed targets fail instead of expanding or recomputing the scope. Existing `purge-pending` tasks continue only through their independent retry flow. Canonical exclusive-directory checks authorize session-owned deletion; they do not claim broad filesystem deletion guarantees, and uncertain outcomes retain their durable records.
 
+The orphan routes are the only place this plugin destroys a session that was never archived. `GET /orphans` lists the residue: subagent sessions whose parent no longer exists, plus top-level sessions that never recorded a turn. A subagent whose parent is still stored is reachable through that parent and is not listed, and neither is a branched chat, which is an independent conversation. Blankness cannot be read from a header, so it is decided by reading the log, and the scan yields cooperatively and supports cancellation instead of silently truncating a fixed prefix. Operation checks inspect only selected blank candidates and preserve unreadable logs.
+
+`POST /orphans/delete` and `POST /orphans/export` never trust the id list they are handed: both recompute the orphan set and refuse the entire request with `orphan-set-changed` when any id is invalid at the start of the operation. Each item is checked again before its deletion; later external Host changes can produce partial results. Being an orphan is what replaces the archive precondition, so without that check the route would delete any session by id. Delete reuses the whole permanent-delete path — exclusive-directory verification, snapshot sweeping, live disposal, the durable `purge-pending` intent, and the registry index purge — with the archive precondition as the single step lifted. Export reuses the archive export writer and its budgets, and like `/export` it accepts a bounded native form with no guard header. Preview and preview-image accept `scope: "orphan"`, whose visibility authority is the same recomputed orphan set.
+
+The product entry uses `kind=subagent` for scan, export and delete, with `scope: "orphan-subagent"` for strict previews. Requests without kind retain legacy compatibility. Strict deletion persists `purgeSelectedOnly: true` on pending records and removes selected IDs only; restart recovery does not expand the descendant tree.
+
 ## State, ownership, and durability
 
 Plugin state lives under `$DSH_HOME/plugin-data/archived-chats/`:
@@ -86,12 +98,12 @@ Metadata and recycle writes are serialized and published through temporary files
 
 ## Workspace bulk archive
 
-The client registers `settings.section` and `shell.overlay`. Its workspace chooser lives in **Settings → Archive Management / 设置 → 归档管理**, without depending on a workspace-menu extension or shared client store.
+The client registers `settings.section` and `shell.overlay`. Its Unarchived conversation list lives in **Settings → Archive Management / 设置 → 归档管理**, without depending on a workspace-menu extension or shared client store.
 
-1. List workspaces containing at least one eligible chat.
-2. Prepare each selected workspace separately. A preview binds at most 2,000 ordered IDs to a five-minute, single-use token/nonce.
-3. Skip workspaces that became empty; show one aggregate confirmation, or return to the refreshed chooser if all are empty.
-4. Apply credentials in selection order and combine results; partial failure in one workspace does not automatically stop later workspaces.
+1. List workspace conversations in Unarchived, excluding archived, recycled, pending deletion, and subagent rows. Use `readSession` for cold forks and preserve metadata.
+2. Individual archiving binds `sessionIds`; workspace and global actions cover complete workspaces regardless of search or filters. A stale individual target fails rather than expanding scope.
+3. Show one aggregate confirmation. Empty preparations return to the refreshed list.
+4. Apply token/nonce confirmations, rechecking membership and running status after asynchronous inspection. Refresh archive, Unarchived, sidebar, and storage consumers after success.
 
 Apply accepts credentials, not caller-added session IDs. Under the lifecycle queue, each chat is rechecked for workspace membership, archive state, agent state, and a real `turn/start`. Blank chats yield `session-empty`; unverifiable content yields `session-unavailable`. Older Hosts without agent status conservatively skip loaded chats. Candidate inspection concurrency is eight.
 
@@ -125,7 +137,9 @@ Turn projection retains recorded boundaries and process/final-response positions
 
 Export download uses a guarded fetch, validates status, ZIP content type, and attachment disposition, then buffers the complete response before creating a Blob URL. It has a five-minute end-to-end timeout and a 320 MiB response-byte cap for declared and streamed bodies. The cap is not a peak-heap guarantee because chunks, the contiguous buffer, and Blob can coexist; the non-stream WebView fallback has no stronger universal memory ceiling. Completion says the download started, not that the browser saved it to disk.
 
-Archive row actions are preview, edit tags/note, Unarchive, and Delete. The header exposes Bulk archive and More; More contains Import backup, Export all, Unarchive all, a separator, and Delete all. Header geometry stays consistent across tabs. Workspace menus contain Unarchive all, Move all to Recycle Bin, Export all, a separator, and Delete all; every action confirms the full workspace name and complete archive count. Global export/unarchive/delete confirms all archived chats across workspaces, excluding trash. Filters do not narrow these scopes. Delete/Delete all labels lead to concise irreversible-action confirmation naming the chat, workspace, or global scope. Recycle rows retain the preview icon and use compact Restore/Delete text buttons matching archive rows. Recycle workspace actions are Restore all and Delete all; its header directly offers text-only Restore all and Empty Recycle Bin, without a More menu. Empty still requires irreversible-action confirmation. Primary buttons and selected tabs use neutral theme colors that invert in dark mode, while destructive actions remain red. Workspace/global restoration separately confirms the workspace name or global workspace count, eligible chat counts, and Archived destination, skipping purge-pending. A synchronous submission lock prevents duplicates; results retain actual success/failure counts and View Archived navigation. Both deleted and pending IDs leave actionable archive rows while failures remain explained and related state refreshes.
+Archive row actions are preview, edit tags/note, Unarchive, and Delete. The header exposes More; Unarchived reuses `GroupSection`, with search above filters and a refresh icon at the right; rows offer a read-only preview icon and Archive, while workspace menus and the header offer Archive all; More contains Import backup, Export all, Unarchive all, a separator, and Delete all. Header geometry stays consistent across tabs. Workspace menus contain Unarchive all, Move all to Recycle Bin, Export all, a separator, and Delete all; every action confirms the full workspace name and complete archive count. Global export/unarchive/delete confirms all archived chats across workspaces, excluding trash. Filters do not narrow these scopes. Delete/Delete all labels lead to concise irreversible-action confirmation naming the chat, workspace, or global scope. Recycle rows retain the preview icon and use compact Restore/Delete text buttons matching archive rows. Recycle workspace actions are Restore all and Delete all; its header directly offers text-only Restore all and Empty Recycle Bin, without a More menu. Empty still requires irreversible-action confirmation. Primary buttons and selected tabs use neutral theme colors that invert in dark mode, while destructive actions remain red. Workspace/global restoration separately confirms the workspace name or global workspace count, eligible chat counts, and Archived destination, skipping purge-pending. A synchronous submission lock prevents duplicates; results retain actual success/failure counts and View Archived navigation. Both deleted and pending IDs leave actionable archive rows while failures remain explained and related state refreshes.
+
+Plugin confirmation, preview, import, metadata, storage, and retention dialogs share the opaque `--dsw-alias-bg-layer-2` surface and Host prominent elevation, with a legacy shadow fallback. Menus and toasts use opaque theme layers. Masks and hover states retain their intentional transparency; frosted menu tokens are not used as dialog backgrounds.
 
 ## About and version discovery
 
@@ -163,6 +177,10 @@ Snapshot sweeping uses manifest ownership and the record's named snapshotId to c
 
 Failures retain purge-pending. Startup and runtime retries continue these tasks, never restore them to ordinary chats. Archive deletion rejects existing recycle records, protecting the Recycle Bin from archive-wide Delete all. Purging snapshot copies does not promise global attachment cleanup or Host session_projcache eviction; no corresponding safe public eviction API is used.
 
+Destroying a session also destroys its subagent descendants, transitively, so a deletion cannot strand sessions that no workspace owns and no view lists. Session ids are stored in two dialects — a bare UUID and the same UUID behind `session-` — and one edge may mix them, so every parent/child comparison normalizes first; without that, each parent looks absent and the cascade silently finds nothing. Only `origin: "subagent"` edges are followed. A branched chat keeps a pointer to the chat it came from but is an independent conversation, so neither it nor its own subagents are cascade targets. Descendants are resolved *before* the parent is destroyed, because a child edge is only visible while its parent is still listed; resolving afterwards would strand exactly the sessions the cascade exists to remove.
+
+Cascade runs on the permanent paths only: direct archive deletion, recycle purge, Empty Recycle Bin, and automatic retention. A move to the Recycle Bin leaves the original log on disk, so its subagents are not orphans yet — they become orphans exactly when the parent's log is destroyed, which is where the cascade runs. Descendants are never archived, so they take the direct permanent-delete path with only the archive precondition lifted; exclusive-directory verification, snapshot sweeping, live disposal, and registry index cleanup are all shared with an archived session. A descendant that already owns a recycle record keeps its own lifecycle, and a parent whose own deletion failed still exists, so its subagents are kept.
+
 ## Startup recovery and old-data cleanup
 
 recoverStartup performs:
@@ -214,6 +232,10 @@ npm pack --dry-run --json
 git diff --check
 ```
 
-The native commands install the locked `@deepseek-ai/dsh-session@0.1.7-rc.2` fixture and require all six native integration cases to run without skips. This is the local equivalent of the mandatory native Host integration gate in CI.
+The native commands install the locked `@deepseek-ai/dsh-session@0.1.7-rc.2` fixture and require all seven native integration cases to run without skips. This is the local equivalent of the mandatory native Host integration gate in CI.
+
+The declared DSH `>=0.1.0-rc.7` range remains capability-based. Release automation tests Node.js 18 on Ubuntu and Node.js 24 on Ubuntu, macOS, and Windows; the Node.js 24 matrix requires the official `@deepseek-ai/dsh-session@0.1.7-rc.2` Host backend integration (7/7) and package checks, including the v4 session format. The [screenshots](../screenshots.json) show the current interface with synthetic example chats.
+
+Permanent deletion quiesces live agents before the final descendant inventory. Optional `cascadeSessionIds` in the parent purge-pending record persist the complete targets until every descendant finishes, so startup can recover after the parent directory disappears. Forks and subtrees with independent recycle records remain outside the cascade. Do not downgrade to a version that does not understand this field while these records are pending.
 
-The declared DSH `>=0.1.0-rc.7` range remains capability-based. Release automation tests Node.js 18 on Ubuntu and Node.js 24 on Ubuntu, macOS, and Windows; the Node.js 24 matrix requires the official `@deepseek-ai/dsh-session@0.1.7-rc.2` Host backend integration (6/6) and package checks, including the v4 session format. The [screenshots](../screenshots.json) show the current interface with synthetic example chats.
+`GET /unarchived` is read-only; `/unarchived/export` and preview `scope: "unarchived"` validate current workspace visibility. Normal conversations gain no direct permanent-delete route. Cleanup UI retains `/orphans` authority checks.

package/docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 [English](ARCHITECTURE.en.md) · 中文 · [用户指南](USER_GUIDE.zh-CN.md)
 
-本文跟随 `main` 分支，功能对应 1.4.6。本版修复旧版与当前版本会话日志混存时，永久删除及回收站清空失败的问题。版本变更见[更新日志](../CHANGELOG.md)。运行时代码是接口与行为的依据；用户操作说明与本文应保持一致。
+本文跟随 `main` 分支，功能对应 1.5.0。本版新增未归档管理和按需残留会话检查，修复子代理级联删除与浮层背景。版本变更见[更新日志](../CHANGELOG.md)。运行时代码是接口与行为的依据；用户操作说明与本文应保持一致。
 
 ## 产品边界与模块
 
@@ -11,7 +11,7 @@
 | 模块（均位于 `lib/`） | 职责 |
 | --- | --- |
 | `index.js` | Host 能力解析、路由、归档可见性、生命周期队列及物理删除 |
-| `client.js` | 设置页、五个主视图、弹窗、原生归档提示与请求状态 |
+| `client.js` | 设置页、六个主视图、弹窗、原生归档提示与请求状态 |
 | `about.js` | 本地插件信息、受限的公开版本查询与运行期缓存 |
 | `persistence-compat.js` | 旧版 inspect 与新版只读句柄适配，独立标题读取 |
 | `workspace-bulk-archive.js` | 工作区归档候选、短效确认、执行重检 |
@@ -21,6 +21,7 @@
 | `search.js`、`stats.js`、`insights.js` | 消息投影与搜索、会话目录测量、空间分账 |
 | `retention.js`、`retention-service.js`、`auto-retention.js` | 策略、确认与重检、启动恢复及定时任务 |
 | `lineage.js` | 只读来源、分叉与子代理关系投影 |
+| `session-graph.js` | 会话 ID 归一化、子代理后代解析与孤儿分类 |
 
 界面仅通过工作区操作移入回收站；单条可永久删除或取消归档。保留工作区导出与全部导出。后端兼容接口可接收单条 ID，不代表界面提供单条移入入口。
 
@@ -57,6 +58,11 @@ POST /plugins/dsh-archived-chats/unarchive
 POST /plugins/dsh-archived-chats/unarchive-all
 POST /plugins/dsh-archived-chats/delete
 POST /plugins/dsh-archived-chats/delete-all
+GET  /plugins/dsh-archived-chats/unarchived
+POST /plugins/dsh-archived-chats/unarchived/export
+GET  /plugins/dsh-archived-chats/orphans
+POST /plugins/dsh-archived-chats/orphans/delete
+POST /plugins/dsh-archived-chats/orphans/export
 ```
 
 除导出外，上述 POST 路由要求 `x-dsh-archived-chats: 1`。读取对话内容的预览、图片、搜索也使用受保护 POST。导出单独接受有界原生表单，不使用此 header 守卫，并检查所请求会话的当前归档可见性；其余路由按各自限定解析载荷。
@@ -67,6 +73,12 @@ POST /plugins/dsh-archived-chats/delete-all
 
 回收接口分别调用 `restore`、`purge`、`empty`。empty 要求确认时捕获的精确 `trashed`／`degraded` 记录实例，包括回收与快照身份。服务只清理这些目标：之后新增的记录被排除，已变更目标失败，不扩大或重算范围。已有 `purge-pending` 任务只由独立重试流程续作。规范的独占目录检查只授权删除会话所有的目标，不是广义文件系统删除保证；结果不确定时保留持久记录。
 
+孤儿路由是本插件唯一销毁从未归档会话的地方。`GET /orphans` 列出残留：父会话已不存在的子代理会话，以及从未记录任何轮次的顶层会话。父会话仍在存储中的子代理可经由该父访问，因此不列出；分叉会话是独立会话，同样不列出。空白无法从 header 判断，只能读取日志决定，扫描定期让出事件循环并支持请求取消，不按固定前缀静默截断；操作校验只检查请求中选定的空会话。无法读取日志时保留会话。
+
+`POST /orphans/delete` 与 `POST /orphans/export` 绝不信任收到的 ID 列表：两者都重新计算孤儿集合，开始操作时只要有一个 ID 已不再是孤儿，就整体拒绝并返回 `orphan-set-changed`。孤儿身份正是替代归档前置校验的东西；没有这项检查，该路由就能按 ID 删除任意会话。删除完整复用永久删除路径——独占目录校验、快照清扫、活动会话处置、持久 `purge-pending` 意图与注册表索引清理——仅解除归档前置校验这一步。导出复用归档导出写入器及其预算，并且与 `/export` 一样接受有界原生表单、不使用 guard header。预览与图片预览接受 `scope: "orphan"`，其可见性依据是同一个重新计算的孤儿集合。
+
+产品入口使用 `kind=subagent` 查询参数限定扫描、导出和删除范围；严格预览使用 `scope: "orphan-subagent"`。无 kind 的旧接口保留兼容。严格删除将 `purgeSelectedOnly: true` 持久保存到待删除记录，只删除选中项，重启续作不会重新展开子代理树。
+
 ## 状态、所有权与持久化
 
 插件状态根目录是 `$DSH_HOME/plugin-data/archived-chats/`：
@@ -86,12 +98,12 @@ Host 的归档注册表决定归档归属；正常可见归档列表排除回收
 
 ## 工作区批量归档
 
-客户端注册 `settings.section` 和 `shell.overlay`，在 **Settings → Archive Management / 设置 → 归档管理** 内维护工作区选择器，不依赖工作区菜单扩展或共享客户端 store。
+客户端注册 `settings.section` 和 `shell.overlay`，在 **Settings → Archive Management / 设置 → 归档管理** 内维护未归档会话列表，不依赖工作区菜单扩展或共享客户端 store。
 
-1. 列出至少有一条符合条件聊天的工作区。
-2. 浏览器为每个选中工作区分别请求 preview；每个 preview 最多绑定 2,000 个有序 ID，凭据 token/nonce 有效 5 分钟且仅用一次。
-3. 跳过准备期间变空的工作区，显示一次汇总确认；全部变空则返回更新后的选择器。
-4. 按选择顺序 apply 各工作区凭据，汇总结果；后续工作区不会因前一个部分失败而自动停止。
+1. 未归档列表读取工作区会话，排除已归档、回收、待删除及子代理行；冷分叉通过 `readSession` 读取，保留标签备注。
+2. 单条归档用 `sessionIds` 限定 ID；工作区与全局操作覆盖完整工作区，范围不随搜索或筛选改变。失效的单条目标整体拒绝，不扩大范围。
+3. 显示一次汇总确认；空准备返回刷新后的列表。
+4. 执行 token/nonce 确认，在异步读取后重检工作区及运行状态。成功后刷新归档、未归档、侧栏及空间状态。
 
 apply 只接受凭据，不接受调用方增补会话 ID。每条执行前在生命周期队列内检查工作区归属、归档状态、agent 状态及真实 `turn/start`。空白为 `session-empty`，内容无法确认则 `session-unavailable`；没有 agent 状态的旧 Host 会保守跳过已加载会话。候选内容检查最多并发 8 条。
 
@@ -125,7 +137,9 @@ apply 只接受凭据，不接受调用方增补会话 ID。每条执行前在
 
 导出下载使用受保护 fetch，验证状态、ZIP 内容类型和附件 disposition，缓冲完整响应后才创建 Blob URL。端到端超时为五分钟，已声明及流式响应上限为 320 MiB 字节。该上限不是峰值堆内存保证，因为分块、连续缓冲区和 Blob 可能同时存在；非流式 WebView 回退也没有更强的通用内存上限。完成文案表示已开始下载，不表示浏览器已保存到磁盘。
 
-归档行操作为预览、编辑标签备注、取消归档、删除。顶部提供批量归档和更多；更多菜单依次为导入备份、全部导出、全部取消归档、分隔线、全部删除，各 Tab 顶部保持一致尺寸。工作区菜单依次为全部取消归档、全部移入回收站、全部导出、分隔线、全部删除，每项均确认完整工作区名称和全部归档聊天数。全局导出／取消归档／删除确认所有工作区归档数量，排除回收站；筛选不缩小这些范围。「删除／全部删除」进入简短的不可恢复确认，点明聊天、工作区或全局范围。回收站聊天行保留预览图标，恢复／删除使用与归档行一致的紧凑文字按钮。工作区操作为全部恢复和全部删除；顶部直接并列显示纯文字的全部恢复和清空回收站，不再设置更多菜单；清空仍须不可恢复确认。主按钮和选中 Tab 使用随深色模式反转的黑白主题色，危险操作保留红色。两级恢复确认分别说明工作区名称或全局工作区数、可恢复聊天数及已归档去向，跳过 purge-pending。同步提交锁避免重复请求；反馈保留实际成功／失败数量及查看已归档入口。永久删除响应中的 deleted 和 pending 都从可操作归档列表移除，同时保留失败说明并刷新相关状态。
+归档行操作为预览、编辑标签备注、取消归档、删除。顶部提供更多；未归档复用 `GroupSection`，搜索在筛选行上方，刷新图标靠右；会话行提供只读预览图标和归档，工作区菜单和顶部提供全部归档；更多菜单依次为导入备份、全部导出、全部取消归档、分隔线、全部删除，各 Tab 顶部保持一致尺寸。工作区菜单依次为全部取消归档、全部移入回收站、全部导出、分隔线、全部删除，每项均确认完整工作区名称和全部归档聊天数。全局导出／取消归档／删除确认所有工作区归档数量，排除回收站；筛选不缩小这些范围。「删除／全部删除」进入简短的不可恢复确认，点明聊天、工作区或全局范围。回收站聊天行保留预览图标，恢复／删除使用与归档行一致的紧凑文字按钮。工作区操作为全部恢复和全部删除；顶部直接并列显示纯文字的全部恢复和清空回收站，不再设置更多菜单；清空仍须不可恢复确认。主按钮和选中 Tab 使用随深色模式反转的黑白主题色，危险操作保留红色。两级恢复确认分别说明工作区名称或全局工作区数、可恢复聊天数及已归档去向，跳过 purge-pending。同步提交锁避免重复请求；反馈保留实际成功／失败数量及查看已归档入口。永久删除响应中的 deleted 和 pending 都从可操作归档列表移除，同时保留失败说明并刷新相关状态。
+
+所有插件确认、预览、导入、元数据、空间和保留策略弹窗共用不透明的 `--dsw-alias-bg-layer-2` 背景及宿主 prominent elevation，兼容旧版阴影。菜单和提示使用不透明主题层；遮罩与悬停状态保留各自的半透明用途，避免将磨砂菜单 token 直接用于弹窗主体。
 
 ## 关于与版本查询
 
@@ -163,6 +177,10 @@ apply 只接受凭据，不接受调用方增补会话 ID。每条执行前在
 
 失败保留 `purge-pending`。启动恢复和运行中的重试继续处理这些任务，不将其恢复为普通聊天。归档删除拒绝已有回收记录，所以归档页全部删除不会波及回收站。删除快照副本不承诺清除 Host 全局附件或 `session_projcache`；插件没有对应的安全公开 eviction API。
 
+删除会话会连带递归删除其全部子代理后代，因此一次删除不会遗留任何工作区都不拥有、任何视图都不列出的会话。会话 ID 以两种方言存储——裸 UUID 与带 `session-` 前缀的同一 UUID——且同一条边可能混用，因此每次父子比较都先归一化；不做归一化时每个父都判为缺失，级联会静默地什么都找不到。只沿 `origin: "subagent"` 的边遍历。分叉会话保留指向来源会话的指针，但它是独立会话，因此它本身及其子代理都不是级联目标。后代在父会话被销毁**之前**解析：子边只在父仍在清单中时可见，之后再解析只会遗留那些级联本应删除的会话。
+
+级联只在永久路径上执行：归档直接永久删除、回收站永久删除、清空回收站、自动保留清理。移入回收站不删除原日志，其子代理此时还不是孤儿——它们恰好在父日志被销毁时成为孤儿，而级联正运行在那里。后代从未归档，因此走直接永久删除路径，仅解除归档前置校验；独占目录校验、快照清扫、活动会话处置与注册表索引清理都与归档会话共用。已有回收记录的后代保留自己的生命周期；自身删除失败的父会话仍然存在，因此其子代理被保留。
+
 ## 启动恢复与旧数据清理
 
 `recoverStartup` 依次：
@@ -216,4 +234,8 @@ git diff --check
 
 原生集成命令会安装锁定的 `@deepseek-ai/dsh-session@0.1.7-rc.2` fixture，并要求六个原生集成用例全部执行且不能跳过；这是 CI 强制原生 Host 集成门禁的本地等价检查。
 
-声明的 DSH `>=0.1.0-rc.7` 范围仍以 Host 公开能力为准。发布自动化在 Ubuntu 上测试 Node.js 18，并在 Ubuntu、macOS 和 Windows 上测试 Node.js 24；Node.js 24 矩阵强制运行基于官方 `@deepseek-ai/dsh-session@0.1.7-rc.2` 的 Host 后端集成（6/6）与打包检查，覆盖 v4 会话格式。[截图](../screenshots.json)使用虚构示例聊天展示当前界面。
+声明的 DSH `>=0.1.0-rc.7` 范围仍以 Host 公开能力为准。发布自动化在 Ubuntu 上测试 Node.js 18，并在 Ubuntu、macOS 和 Windows 上测试 Node.js 24；Node.js 24 矩阵强制运行基于官方 `@deepseek-ai/dsh-session@0.1.7-rc.2` 的 Host 后端集成（7/7）与打包检查，覆盖 v4 会话格式。[截图](../screenshots.json)使用虚构示例聊天展示当前界面。
+
+永久删除在最终读取子代理关系前先取消并释放活动代理。完整后代集合以可选 `cascadeSessionIds` 保存到父会话的 `purge-pending` 记录；父目录消失后也保留该记录，直到所有子代理清理完成。启动重试据此恢复级联，不跨越分叉或已有独立回收记录的子树。待重试记录清空前不要降级到不支持此字段的版本。
+
+`GET /unarchived` 为只读列表；`/unarchived/export` 和预览的 `scope: "unarchived"` 校验当前工作区可见性。普通会话没有新增直接永久删除路由；清理筛选继续使用 `/orphans` 的严格授权校验。

package/docs/USER_GUIDE.md

@@ -2,7 +2,7 @@
 
 English · [简体中文](USER_GUIDE.zh-CN.md) · [Back to README](../README.md)
 
-Archive Management provides a place to browse and manage DSH's archived chats, plus workspace bulk archiving. This document follows the `main` branch and targets 1.4.6. This release fixes permanent deletion and Recycle Bin cleanup when historical and current session log generations coexist. See the [changelog](../CHANGELOG.md) for release history. For interfaces and data formats, see the [architecture](ARCHITECTURE.en.md).
+Archive Management provides a place to browse and manage DSH's archived chats, plus workspace bulk archiving. This document follows the `main` branch and targets 1.5.0. This release adds Unarchived management and on-demand residual chat checks, and fixes subagent cascade deletion and overlay backgrounds. See the [changelog](../CHANGELOG.md) for release history. For interfaces and data formats, see the [architecture](ARCHITECTURE.en.md).
 
 ## Understand the three locations
 
@@ -24,7 +24,7 @@ Alternatively, run this command on the computer running DSH:
 dsh plugin --profile web add dsh-archived-chats@latest
 ```
 
-Restart DSH and open **Settings → Archive Management** (Chinese: **设置 → 归档管理**). The views are **Archived**, **Recycle Bin**, **Storage & Retention**, **Origins & Branches**, and **About**.
+Restart DSH and open **Settings → Archive Management** (Chinese: **设置 → 归档管理**). The views are **Archived**, **Unarchived**, **Recycle Bin**, **Storage & Retention**, **Origins & Branches**, and **About**.
 
 Before updating an older installation, read “Upgrades, old data, and downgrades” below, especially the snapshot-cleanup warning.
 
@@ -32,14 +32,13 @@ Before updating an older installation, read “Upgrades, old data, and downgrade
 
 Use DSH's normal session menu to archive one chat. The success notice offers View and Undo and closes after about three seconds. The plugin groups archived chats by workspace.
 
-To archive in bulk:
+In **Unarchived**, search titles or IDs at the top. The next row provides time/title sorting, workspace filtering, and a refresh icon at the far right. Workspace groups and chat rows use the same layout as Archived.
 
-1. Choose Bulk archive from the settings page.
-2. Select one or more entries in the workspace chooser; clicking Select all again clears selection.
-3. Click the bottom-right Confirm button and review the aggregate count and destination.
-4. Confirm archiving; review the retained itemized results if anything was skipped or failed.
+- Click the eye icon for a read-only preview, or **Archive** on an individual chat.
+- The workspace three-dot menu offers **Archive all** for that workspace.
+- The header **Archive all** covers every workspace in the list.
 
-Only workspaces with eligible chats are listed. Blank sessions, chats in use, and chats whose content cannot be verified are skipped. Chats created after preparation are not included; workspaces that become empty are skipped. The operation does not move chats between workspaces or change workspace directories.
+Search and workspace filters only change display; they do not narrow workspace or global archiving. Review the eligible chat and workspace counts before confirming. Running chats remain visible with individual archiving disabled. Bulk actions skip running, blank, or unverifiable chats. New chats after preparation are excluded; chats that start running or change workspace before apply are skipped. Unarchived offers read-only previews and archiving, without selection, export, deletion, or a cleanup entry. Archiving preserves workspace directories and prior tags and notes.
 
 Search Archived by title, workspace, tags, notes, messages, and tool results. Filter by type, workspace, and tag; sort by time or title. Content matches show excerpts. Long workspace titles wrap to remain fully visible. Click a workspace folder or title to expand or collapse its chats; the open or closed folder reflects the current state. Group collapse state is saved in the browser.
 
@@ -65,14 +64,17 @@ Tags and notes remain local. Unarchiving preserves them; completed permanent del
 | --- | --- | --- |
 | Archived: chat row | Preview, edit tags and note, Unarchive, Delete | One chat |
 | Archived: workspace More menu | Unarchive all, Move all to Recycle Bin, Export all; separator; Delete all | All archived chats in that workspace |
-| Archived: header | Bulk archive, More | Open the workspace chooser or global action menu |
+| Unarchived: chat row | Preview icon, Archive | One chat; archiving requires confirmation |
+| Unarchived: workspace three-dot menu | Archive all | Every eligible chat in that workspace |
+| Unarchived: header | Archive all | Eligible chats across all workspaces |
+| Archived: header | More | Open the global action menu |
 | Archived: header More menu | Import backup, Export all, Unarchive all; separator; Delete all | Export, unarchive, and delete cover archived chats across all workspaces; Import uses the selected ZIP |
 | Recycle Bin: chat row | Preview icon, Restore and Delete text buttons | One recycle record; Delete is permanent after confirmation |
 | Recycle Bin: workspace More menu | Restore all, Delete all | Recycle records in that workspace |
 | Recycle Bin: header | Restore all | Restore eligible entries across all workspaces after confirmation |
 | Recycle Bin: header | Empty Recycle Bin | Permanently delete recycle records across all workspaces after confirmation |
 
-**Moving to the Recycle Bin is available only through workspace actions, not individual rows or a global move-all action.** There is no single-chat export or list multi-select mode. Search and filters do not narrow workspace or global bulk actions.
+**Moving to the Recycle Bin is available only through workspace actions, not individual rows or a global move-all action.** The Archived view has no single-chat export or list multi-select mode; Unarchived provides read-only previews and archiving. Search and filters do not narrow workspace or global bulk actions.
 
 Every archive workspace action asks for confirmation with the full workspace name and its complete archive count. Global Export all, Unarchive all, and Delete all confirmations count archived chats across every workspace, excluding the Recycle Bin. Check these counts even when the list is filtered. The header keeps consistent dimensions when switching tabs.
 
@@ -102,6 +104,16 @@ Once deletion starts, the plugin saves a non-restorable deletion task, removes a
 
 Missing required Host capabilities cause refusal before a deletion task is committed. Removing snapshot attachment copies does not guarantee immediate reclamation of matching bytes in Harness's global attachment store; other references and Host caching or garbage collection may retain them.
 
+Permanent deletion also cleans up the chat's subagent descendants while preserving independent forks. Unarchived lists ordinary workspace chats. Storage & Retention offers an on-demand residual check, described below.
+
+## Residual chat check
+
+In **Storage & Retention**, choose **Start check**. Results show a count, measured storage and check time; opening the page does not start a scan. Open details separately to manage the results. Only subagents with an explicit parent ID whose parent no longer exists are listed. Workspace, archived, recycled and pending-deletion records, empty chats, invalid parent relationships and independent forks are excluded.
+
+Details include full IDs, parent IDs, working directories, dates, sizes and read-only preview icons. Search and select current results without clearing hidden selections. Backups include selected records. When records exceed the backup limit, they are marked and you are asked whether to deselect them and export the rest. Cancelling keeps the original selection.
+
+Permanent deletion requires confirmation and removes selected records and their directories only, preserving unselected descendants. Retries and restart recovery retain that scope. Descendants may become new residual records after their parent is deleted; check, review and back them up separately before cleanup. Changed membership is refused with a visible prompt to select again. Unavailable sizes display “—”; measured bytes include only measured records.
+
 ## Export and import
 
 Choose Export all from the header's More menu to export every archived chat, or from a workspace menu to export only that workspace's archive. Both ask you to confirm the full scope and chat count and exclude Recycle Bin contents. Restore recycled chats to Archived first if you need to export them. Import backup is also in the header's More menu.
@@ -198,7 +210,7 @@ Features depend on public Host capabilities, not just a version number:
 - Version 2 protection records require this or a newer plugin. Before downgrading, restore recycled chats you need to retain and back up plugin data.
 - If `trash.json` cannot be read, Archived is marked unverified, the Recycle Bin is unavailable, and archive mutations such as unarchive, tag/note editing, and deletion are refused instead of guessing.
 
-The declared DSH `>=0.1.0-rc.7` range remains capability-based. Release automation tests Node.js 18 on Ubuntu and Node.js 24 on Ubuntu, macOS, and Windows; the Node.js 24 matrix requires the official `@deepseek-ai/dsh-session@0.1.7-rc.2` Host backend integration (6/6) and package checks, including the v4 session format.
+The declared DSH `>=0.1.0-rc.7` range remains capability-based. Release automation tests Node.js 18 on Ubuntu and Node.js 24 on Ubuntu, macOS, and Windows; the Node.js 24 matrix requires the official `@deepseek-ai/dsh-session@0.1.7-rc.2` Host backend integration (7/7) and package checks, including the v4 session format.
 
 ## Local data and uninstall
 

package/docs/USER_GUIDE.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](USER_GUIDE.md) · 简体中文 · [返回 README](../README.zh-CN.md)
 
-归档管理为 DSH 已归档聊天提供查看和管理页面，并扩展按工作区批量归档。本文跟随 `main` 分支维护，适用于 1.4.6。本版修复旧版与当前版本会话日志混存时，永久删除及回收站清空失败的问题。版本变更见[更新日志](../CHANGELOG.md)，接口和数据格式见[架构说明](ARCHITECTURE.md)。
+归档管理为 DSH 已归档聊天提供查看和管理页面，并扩展按工作区批量归档。本文跟随 `main` 分支维护，适用于 1.5.0。本版新增未归档管理和按需残留会话检查，修复子代理级联删除与浮层背景。版本变更见[更新日志](../CHANGELOG.md)，接口和数据格式见[架构说明](ARCHITECTURE.md)。
 
 ## 先理解三个位置
 
@@ -24,7 +24,7 @@
 dsh plugin --profile web add dsh-archived-chats@latest
 ```
 
-重启 DSH，打开 **设置 → 归档管理**。页面包含 **已归档**、**回收站**、**空间与策略**、**来源与分支**、**关于**。
+重启 DSH，打开 **设置 → 归档管理**。页面包含 **已归档**、**未归档**、**回收站**、**空间与策略**、**来源与分支**、**关于**。
 
 旧版用户更新前，请先阅读下方「升级、旧数据与降级」，尤其是旧快照清理说明。
 
@@ -32,14 +32,13 @@ dsh plugin --profile web add dsh-archived-chats@latest
 
 单条聊天仍使用 DSH 原有会话菜单归档。成功后提示提供「查看」和「撤销」，约 3 秒后关闭。归档后的聊天在插件中按工作区分组。
 
-需要批量归档时：
+在 **未归档** 中，顶部搜索标题或 ID，下一行按时间／标题排序、筛选工作区；右侧刷新图标重新加载列表。列表与已归档使用相同的工作区分组及会话行排版。
 
-1. 在设置页点击「批量归档」。
-2. 在工作区选择器中选择一个或多个工作区；「全选」再次点击会取消全选。
-3. 点击右下角「确定」，核对汇总的聊天数量和归档去向。
-4. 确认归档；如果有跳过或失败，查看保留的逐项结果。
+- 单条聊天点击眼睛图标只读预览内容，或点击「归档」。
+- 工作区三个点菜单中的「全部归档」覆盖该工作区。
+- 顶部「全部归档」覆盖列表中的所有工作区。
 
-选择器仅展示存在可归档聊天的工作区。空白新会话、正在使用或无法确认内容的聊天会被跳过。准备后新增的聊天不纳入本次操作；工作区变空时会跳过。操作不移动聊天所属工作区，也不更改工作区目录。
+搜索和工作区筛选只改变显示，不缩小工作区或全局归档范围。操作会先汇总实际可归档聊天及工作区数量，确认后才执行。正在运行的聊天仍可见，单条归档不可用；批量操作跳过正在运行、空白或内容无法确认的聊天。准备后新增的聊天不纳入此次操作；确认期间开始运行或改变工作区的聊天会跳过。未归档提供只读预览和归档，不提供勾选、导出、删除或「可清理」入口。归档不更改工作区目录，保留已有标签和备注。
 
 在「已归档」中可以搜索标题、工作区、标签、备注、消息和工具结果，按类型、工作区、标签筛选，并按时间或标题排序。正文命中会显示摘要；工作区长标题自动换行、完整显示。点击工作区文件夹或标题可展开／收起聊天，文件夹开合样式表示当前状态，分组折叠状态保存在浏览器中。
 
@@ -65,14 +64,17 @@ dsh plugin --profile web add dsh-archived-chats@latest
 | --- | --- | --- |
 | 已归档：单条聊天 | 预览、编辑标签备注、取消归档、删除 | 当前聊天 |
 | 已归档：工作区「更多」 | 全部取消归档、全部移入回收站、全部导出；分隔线；全部删除 | 该工作区的全部已归档聊天 |
-| 已归档：顶部 | 批量归档、更多 | 打开工作区选择器或全局操作菜单 |
+| 未归档：聊天行 | 预览图标、归档 | 单条聊天；归档需确认 |
+| 未归档：工作区三个点菜单 | 全部归档 | 该工作区的所有可归档聊天 |
+| 未归档：顶部 | 全部归档 | 所有工作区的可归档聊天 |
+| 已归档：顶部 | 更多 | 打开全局操作菜单 |
 | 已归档：顶部「更多」 | 导入备份、全部导出、全部取消归档；分隔线；全部删除 | 导出、取消归档及删除覆盖所有工作区的已归档聊天；导入使用所选 ZIP |
 | 回收站：单条聊天 | 预览图标、恢复和删除文字按钮 | 当前回收条目；删除需确认且不可恢复 |
 | 回收站：工作区「更多」 | 全部恢复、全部删除 | 该工作区的回收条目 |
 | 回收站：顶部 | 全部恢复 | 确认后恢复所有工作区的可恢复条目 |
 | 回收站：顶部 | 清空回收站 | 确认后永久删除所有工作区的回收条目 |
 
-**移入回收站只提供工作区入口，不提供单条或顶部全部移入入口。** 不提供单条导出或列表多选模式。工作区和顶部批量操作不会因搜索、筛选隐藏了部分聊天而缩小范围。
+**移入回收站只提供工作区入口，不提供单条或顶部全部移入入口。** 已归档不提供单条导出或列表多选模式；未归档提供只读预览和归档操作。工作区和顶部批量操作不会因搜索、筛选隐藏了部分聊天而缩小范围。
 
 归档工作区菜单中的每项操作都需确认，弹窗显示完整工作区名称及该工作区全部归档聊天数。全局「全部导出」「全部取消归档」「全部删除」确认统计所有工作区的归档聊天，不包含回收站；筛选列表后仍应核对完整数量。切换 Tab 时顶部操作区保持一致尺寸。
 
@@ -102,6 +104,16 @@ dsh plugin --profile web add dsh-archived-chats@latest
 
 缺少必要 Host 能力时，操作会在提交删除任务前拒绝执行。删除快照附件副本不保证立即释放 Harness 全局附件库中的相同字节；其他会话引用和 Host 缓存／垃圾回收仍可能保留数据。
 
+永久删除聊天时会连带清理其子代理后代，独立分叉会保留。未归档只显示工作区中的普通聊天；「空间与策略」提供按需残留会话检查，详见下节。
+
+## 残留会话检查
+
+在 **空间与策略** 点击「开始检查」，检查完成后显示数量、已测量空间和检查时间；进入页面不会自动扫描。有结果时点击「查看明细」打开管理弹窗。它只列出有明确父会话 ID 且父会话已不存在的子代理，排除工作区、已归档、回收站、待删除中的会话，以及空会话、父关系异常的记录和独立分叉。
+
+明细提供完整 ID、父会话、工作目录、日期、大小和只读预览图标。可搜索并选择当前结果；筛选不会清除已经选中的隐藏项。导出备份覆盖选中项，超出备份限制时标记记录并询问是否取消勾选后导出其余，取消会保留完整选择。
+
+永久删除须再次确认，只删除选中的记录及目录，不级联未选中的后代。失败重试和重启恢复也保持这个范围；后代在父记录删除后可能成为新的残留，可重新检查、查看、备份后另行处理。列表已变化时拒绝不再符合条件的项，并提示重新选择。大小不可测量时显示「—」；统计字节仅包含已测量项。
+
 ## 导出和导入
 
 顶部「更多 → 全部导出」导出全部已归档聊天；工作区菜单「全部导出」仅导出该工作区的归档聊天。两者都先确认完整范围和聊天数量，不包含回收站内容。需要备份回收聊天时，先恢复到已归档。「导入备份」也位于顶部「更多」菜单。
@@ -198,7 +210,7 @@ DSH 运行时约每分钟检查，关闭期间暂停，启动恢复完成后补
 - v2 保护快照需要此版或更新的插件读取；回退旧插件前先恢复需要保留的回收聊天，并备份插件数据。
 - 如果 `trash.json` 无法读取，归档列表会标为未经核对，回收站不可用，并拒绝取消归档、编辑标签备注及删除等归档修改，避免猜测状态。
 
-声明的 DSH `>=0.1.0-rc.7` 范围仍表达基于 Host 公开能力的兼容性。发布自动化在 Ubuntu 上测试 Node.js 18，并在 Ubuntu、macOS 和 Windows 上测试 Node.js 24；Node.js 24 矩阵强制运行基于官方 `@deepseek-ai/dsh-session@0.1.7-rc.2` 的 Host 后端集成（6/6）与打包检查，覆盖 v4 会话格式。
+声明的 DSH `>=0.1.0-rc.7` 范围仍表达基于 Host 公开能力的兼容性。发布自动化在 Ubuntu 上测试 Node.js 18，并在 Ubuntu、macOS 和 Windows 上测试 Node.js 24；Node.js 24 矩阵强制运行基于官方 `@deepseek-ai/dsh-session@0.1.7-rc.2` 的 Host 后端集成（7/7）与打包检查，覆盖 v4 会话格式。
 
 ## 本地数据与卸载