@wangxiaocuo/dsh-session-trash 0.5.1 → 0.6.1

package/README.en.md

@@ -10,7 +10,8 @@ Status: feature complete and covered by the regression suite. macOS has been ver
 
 ## Features
 
-- Right-click a session in the sidebar and choose "Move to trash". The item appears only for cold sessions with no persisted children and no running turn, job, subagent, or scheduled task.
+- Right-click a session in the sidebar and choose "Move to trash". It is available for cold sessions with no running turn, job, subagent, or scheduled task; hidden subagent children move with their parent and are restored together.
+- For sessions that are still open, still running work, or own visible child sessions, the menu keeps a labelled explanatory "Move to trash" item that states why the move is unavailable instead of hiding the entry entirely.
 - After the move, the shared DSH Toast offers one action: Undo. Undo tries a normal restore first and falls back to an orphan restore when the original workspace is gone.
 - The Trash page in Settings shows title, Session ID, original workspace, trashed date, remaining days, size, and status. The list supports search, filters, and paging at 50 rows per page.
 - Row actions include restore, restore as orphan, permanent deletion, removal from the index, copying the Session ID, and revealing the original workspace in Finder or Explorer.
@@ -102,6 +103,8 @@ Defaults apply when `config` is omitted. Invalid values reject activation instea
 
 Right-click a cold session and choose "Move to trash". After the Toast disappears, open Settings, then Trash, and restore the session. If the original workspace directory is gone, the page asks for confirmation and restores the session as an orphan under "Ungrouped". To empty the trash at once, use "Delete all permanently" in the toolbar and confirm; entries that have not expired are deleted too.
 
+Trash rows that own hidden subagent children show a badge with the child count; restore and permanent deletion always cover the whole tree.
+
 The current DSH version keeps a live agent for a session after it is opened, until the Host process exits. An idle session is still live, so the menu item stays hidden. Restart DSH before trashing it, or archive it. A second DSH instance does not detect a session that is live in another process, so do not use one to bypass this check.
 
 ## HTTP API
@@ -111,8 +114,8 @@ 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 |
-| `POST` | `/preflight` | `{ sessionId }` returns `{ eligible: true }` or `{ eligible: false, code, message }` |
-| `POST` | `/trash` | `{ sessionId }`; moves the session directory |
+| `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 }` |
@@ -129,6 +132,8 @@ Restore and maintenance refusals include `TRASH_ENTRY_NOT_FOUND`, `TRASH_STATE_I
 
 `/state.stats.cleanup` reports the last cleanup attempt, the next sweep, a pending retry, consecutive failures, and the last run summary.
 
+`/state` entries gain `subagentCount` (hidden children moved along) and `members` (parent first, each with `sessionId`, `origin`, and `sizeBytes`); `sizeBytes`/`fileCount` cover the whole tree. The `entry` returned by `/trash` uses the same shape.
+
 ## Storage and recovery
 
 ```text
@@ -139,7 +144,9 @@ Restore and maintenance refusals include `TRASH_ENTRY_NOT_FOUND`, `TRASH_STATE_I
   objects/
     <trashId>/
       meta.json             # object metadata
-      session/              # the moved session directory
+      session/              # the moved parent session directory
+      children/
+        <sessionId>/        # hidden subagent child directory moved along
 ```
 
 The index is committed atomically with `tmp`, `fsync`, and `rename`, and the previous commit is kept as `.bak`. On activation and before every sweep, the plugin settles unfinished `trashing`, `restoring`, and `purging` entries. It completes what can be completed, rolls back what can be rolled back, marks uncertain cases as `missing`, and never deletes a session log during that recovery pass.
@@ -148,10 +155,13 @@ A same-filesystem move uses `rename`. A cross-filesystem move copies into a temp
 
 On POSIX filesystems, the trash root uses `0700` permissions and the index and metadata files use `0600`. A lock older than 10 minutes is treated as stale.
 
+The index schema is v2; a v1 index is upgraded automatically on startup and preserved as `.bak`. Older plugin releases cannot read v2 and enter protection mode, so empty the trash before downgrading.
+
 ## Limitations
 
-- The current DSH version keeps an opened session live until the Host process exits. The "Move to trash" item stays hidden for such a session. Restart DSH before trashing it.
-- Parent sessions with persisted children and subagent sessions cannot be trashed on their own. Archive the whole tree instead.
+- The current DSH version keeps an opened session live until the Host process exits. The context menu then shows the explanatory item instead of an actionable move; restart DSH before trashing it.
+- Parent sessions with visible (non-subagent) children cannot be trashed on their own; archive the whole tree instead. Hidden subagent children move with their parent.
+- A trashed tree is restored or deleted as a whole; there is no partial restore. If any member directory is missing, the entry is marked `missing` and can only be purged or forgotten.
 - 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.
@@ -165,19 +175,14 @@ On POSIX filesystems, the trash root uses `0700` permissions and the index and m
 
 ```bash
 pnpm install
-pnpm test
-npm run test:e2e
+pnpm test          # unit tests
+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` boots a real `dsh web` Host in a temporary `DSH_HOME` and runs the full flow. It uses `/Applications/DeepSeek Harness.app` by default; set `DSH_ELECTRON` to another Electron executable. Set `DSH_E2E_KEEP=1` to keep the temporary home and logs.
-
-The Host smoke test needs a separate temporary `DSH_HOME`:
+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. CI (GitHub Actions) runs the unit tests, the smoke test, and a package-contents check; the end-to-end suite needs a local DeepSeek Harness desktop install and is run manually.
 
-```bash
-DSH_HOME=$(mktemp -d) ELECTRON_RUN_AS_NODE=1 \
-  "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" \
-  test/smoke-host.mjs
-```
+`npm run test:e2e` boots a real `dsh web` Host in a temporary `DSH_HOME` and runs the full flow. It uses `/Applications/DeepSeek Harness.app` by default; set `DSH_ELECTRON` to another Electron executable. Set `DSH_E2E_KEEP=1` to keep the temporary home and logs.
 
 Project layout:
 

package/README.md

@@ -6,13 +6,15 @@
 
 DeepSeek Harness 的会话回收站插件。冷会话可以从侧边栏移出，日志保留在本地；保留期内可以恢复，到期后自动删除日志。面向 DSH 0.2.2-rc.1 的 Desktop 和 Web，Host 和 Client 在同一个包里，不需要构建步骤。
 
-当前状态：功能已实现，回归测试通过。macOS 已在真实 DSH Host 上验证；Windows 和 Linux 的路径、锁、重试规则有单测覆盖，尚未在真实主机上运行。
+当前状态：功能已实现，回归测试与真实 Host 端到端测试通过。macOS 已在真实 DSH Host 上验证；Windows 和 Linux 的路径、锁、重试规则有单测覆盖，尚未在真实主机上运行。
 
 ## 功能
 
-- 侧边栏右键会话，选择「移入回收站」。只有冷会话、没有持久化子会话、也没有运行中的 turn、job、subagent 或定时任务时，菜单项才会出现。
+- 侧边栏右键会话，选择「移入回收站」。只有冷会话、没有运行中的 turn、job、subagent 或定时任务时才能移入；会话跑过的隐藏 subagent 子会话会随父会话一起移入、一起恢复。
+- 对仍打开的会话、正在运行的会话或含可见子会话的会话，菜单保留一个带原因的「移入回收站」说明项：点开解释为什么暂时不能移入，而不是把菜单项直接隐藏。
 - 移入后显示 DSH 共享 Toast，只有「撤销」一个动作。撤销先尝试正常恢复，原工作区不存在时改为孤儿恢复。
 - 设置页「回收站」显示标题、Session ID、原工作区、移入时间、剩余天数、大小和状态。列表支持搜索、筛选，每页 50 条。
+- 含子会话的条目显示「含 N 个子会话」徽章；恢复和永久删除按整棵树处理，不做部分恢复。
 - 行操作包括恢复、恢复为孤儿会话、永久删除、从索引移除、复制 Session ID，以及在 Finder 或资源管理器中显示原工作区。
 - 工具栏「永久删除全部」在二次确认后清空回收站：删除所有已移入的会话日志，并把文件缺失的记录移出索引；附件、图片和搜索索引等衍生物不删除。
 - 默认保留 30 天，每 6 小时扫描一次；插件激活后和打开回收站页面时也会检查。清理失败按指数退避重试，失败信息显示在页面上。
@@ -102,7 +104,7 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 
 右键冷会话选择「移入回收站」。Toast 消失后，仍可从设置页「回收站」恢复；原工作区目录已不存在时，页面会先确认，确认后会话回到「未分组」。需要清空时点工具栏「永久删除全部」并确认，未过期的条目也会删除。
 
-当前 DSH 版本会把打开过的会话保留为 live agent，直到该 Host 进程结束。会话即使空闲也算 live，菜单项不会出现；需要回收时先重启 DSH，或直接归档。另一个 DSH 实例不会识别这种 live 状态，不要用它绕过限制。
+当前 DSH 版本会把打开过的会话保留为 live agent，直到该 Host 进程结束。会话即使空闲也算 live，此时右键菜单显示的是带原因的说明项、不能移入；需要回收时先重启 DSH，或直接归档。另一个 DSH 实例不会识别这种 live 状态，不要用它绕过限制。
 
 ## HTTP API
 
@@ -111,8 +113,8 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 | 方法 | 路径 | 说明 |
 |---|---|---|
 | `GET` | `/state` | 配置、索引状态、条目、统计和清理诊断；打开页面时可能触发一次节流清理 |
-| `POST` | `/preflight` | `{ sessionId }` 返回 `{ eligible: true }` 或 `{ eligible: false, code, message }` |
-| `POST` | `/trash` | `{ sessionId }`，移动会话目录 |
+| `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 }` |
@@ -129,6 +131,8 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 
 `/state` 的 `stats.cleanup` 记录上次清理时间、下次清理时间、重试时间、连续失败次数和上次运行摘要。
 
+`/state` 的条目新增 `subagentCount`（一并移入的隐藏子会话数）和 `members`（父会话在前，含 `sessionId`、`origin`、`sizeBytes`）；`sizeBytes`/`fileCount` 是整棵树的总量。`/trash` 返回的 `entry` 使用同一形状。
+
 ## 数据与恢复
 
 ```text
@@ -139,7 +143,9 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
   objects/
     <trashId>/
       meta.json             # 对象元数据
-      session/              # 被移动的会话目录
+      session/              # 被移动的父会话目录
+      children/
+        <sessionId>/        # 一并移入的隐藏 subagent 子会话目录
 ```
 
 索引通过 `tmp`、`fsync`、`rename` 原子提交，旧版本保留为 `.bak`。启动时和每次清理前，插件会处理未完成的 `trashing`、`restoring`、`purging` 状态：能完成的完成，能回滚的回滚，无法判断的标记为 `missing`，不会删除会话日志。
@@ -148,10 +154,13 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 
 在 POSIX 文件系统上，回收站目录权限为 `0700`，索引和元数据为 `0600`。锁文件超过 10 分钟未更新时视为陈旧。
 
+索引 schema 为 v2，v1 索引会在启动时自动升级并保留为 `.bak`。旧版本插件读不懂 v2 索引，会进入保护模式；降级前请先清空回收站。
+
 ## 限制
 
 - 当前 DSH 版本中，打开过的会话会保持 live 直到 Host 进程结束，因此不会显示「移入回收站」。需要回收时重启 DSH。
-- 带子会话的父会话和 subagent 会话不能单独回收，只能归档整棵树。
+- 带可见子会话（非 subagent）的父会话不能回收，只能归档整棵树；subagent 的隐藏子会话随父会话一起移入。
+- 整棵树按整体恢复或删除，不做部分恢复：任一成员目录缺失时条目会标记为 `missing`，只能永久删除或从索引移除。
 - 孤儿恢复不会重建原工作区目录，也不会重新挂到工作区。
 - 归档和置顶状态会跨回收、恢复保留，回收站页面不管理这两个集合。
 - 永久删除只删除会话日志。附件、图片、投影缓存和搜索索引不会被删除。
@@ -165,19 +174,14 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 
 ```bash
 pnpm install
-pnpm test
-npm run test:e2e
+pnpm test          # 单元测试
+pnpm test:smoke    # Host 冒烟测试（真实 Cordis，普通 Node 即可）
+npm run test:e2e   # 真实 dsh web 端到端（需要本机桌面版）
 ```
 
-`npm run test:e2e` 会启动真实 `dsh web` Host，在临时 `DSH_HOME` 中跑完整流程。默认使用 `/Applications/DeepSeek Harness.app`，也可以用 `DSH_ELECTRON` 指向其他 Electron 可执行文件。设置 `DSH_E2E_KEEP=1` 可以保留临时目录和日志。
-
-Host 冒烟测试需要单独的临时 `DSH_HOME`：
+Host 冒烟测试通过 `@deepseek-ai/cordis` 这个 devDependency 装配真实插件上下文，自己创建并清理临时 `DSH_HOME`，不需要桌面版；设置 `DSH_SMOKE_KEEP=1` 可以保留临时目录用于排查。CI（GitHub Actions）会跑单元测试、冒烟测试和打包内容检查；e2e 依赖本机的 DeepSeek Harness 桌面版，需要手动执行。
 
-```bash
-DSH_HOME=$(mktemp -d) ELECTRON_RUN_AS_NODE=1 \
-  "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" \
-  test/smoke-host.mjs
-```
+`npm run test:e2e` 会启动真实 `dsh web` Host，在临时 `DSH_HOME` 中跑完整流程。默认使用 `/Applications/DeepSeek Harness.app`，也可以用 `DSH_ELECTRON` 指向其他 Electron 可执行文件。设置 `DSH_E2E_KEEP=1` 可以保留临时目录和日志。
 
 项目结构：
 

package/client.js

@@ -24,6 +24,18 @@ window.__ModuleLoader__.load({
       'workspace-missing': 'filterWorkspaceMissing',
       expiring: 'filterExpiring',
     }
+    /**
+     * Preflight refusals the user can act on themselves. Those keep a visible
+     * menu entry that explains the refusal instead of hiding it.
+     */
+    const MOVE_BLOCKED_KEYS = {
+      SESSION_LIVE: { label: 'moveBlockedLive', toast: 'blockedLiveToast' },
+      SESSION_ACTIVE: { label: 'moveBlockedActive', toast: 'blockedActiveToast' },
+      SESSION_HAS_DESCENDANTS: {
+        label: 'moveBlockedDescendants',
+        toast: 'blockedDescendantsToast',
+      },
+    }
 
     /** Open trash views subscribe here so one successful mutation refreshes them all. */
     const revisionListeners = new Set()
@@ -110,6 +122,7 @@ window.__ModuleLoader__.load({
       badgeMigration: '需要迁移',
       badgeExpiring: '即将到期',
       badgeExpired: '已过期',
+      badgeSubagents: '含 {count} 个子会话',
       stateTrashing: '正在移入…',
       stateRestoring: '正在恢复…',
       statePurging: '正在删除…',
@@ -153,9 +166,16 @@ window.__ModuleLoader__.load({
       lastErrorLabel: '上次错误：{message}',
       footnote: '回收站目录：{path}',
       move: '移入回收站',
+      moveBlockedLive: '移入回收站（会话已打开）',
+      moveBlockedActive: '移入回收站（有任务在运行）',
+      moveBlockedDescendants: '移入回收站（含可见子会话）',
       undo: '撤销',
       undoFailed: '撤销失败',
       trashSuccess: '已将「{title}」移入回收站',
+      trashSuccessTree: '「{title}」及其 {count} 个子会话已移入回收站',
+      blockedLiveToast: '该会话已在本机打开。DSH 目前不会释放已打开的会话，请重启 DSH 后再移入回收站。',
+      blockedActiveToast: '该会话还有正在运行的任务或子代理，等它停下来后再移入回收站。',
+      blockedDescendantsToast: '该会话包含可见的子会话，只能使用 DSH 自带的「归档」整棵会话树。',
       restoreSuccess: '已恢复「{title}」',
       restoreOrphanSuccess: '已恢复为孤儿会话「{title}」',
       purgeSuccess: '已永久删除「{title}」',
@@ -239,6 +259,7 @@ window.__ModuleLoader__.load({
       badgeMigration: 'Migration required',
       badgeExpiring: 'Expiring soon',
       badgeExpired: 'Expired',
+      badgeSubagents: '{count} sub-sessions',
       stateTrashing: 'Moving…',
       stateRestoring: 'Restoring…',
       statePurging: 'Deleting…',
@@ -282,9 +303,16 @@ window.__ModuleLoader__.load({
       lastErrorLabel: 'Last error: {message}',
       footnote: 'Trash directory: {path}',
       move: 'Move to trash',
+      moveBlockedLive: 'Move to trash (session is open)',
+      moveBlockedActive: 'Move to trash (work is running)',
+      moveBlockedDescendants: 'Move to trash (has visible sub-sessions)',
       undo: 'Undo',
       undoFailed: 'Could not undo',
       trashSuccess: 'Moved “{title}” to the trash',
+      trashSuccessTree: '“{title}” and its {count} sub-sessions were moved to the trash',
+      blockedLiveToast: 'This session is open in DSH. DSH does not release opened sessions yet; restart DSH, then move it to the trash.',
+      blockedActiveToast: 'This session still has running work; wait for it to stop, then move it to the trash.',
+      blockedDescendantsToast: 'This session has visible child sessions; use the built-in Archive action for the whole tree instead.',
       restoreSuccess: 'Restored “{title}”',
       restoreOrphanSuccess: 'Restored “{title}” as an orphan session',
       purgeSuccess: 'Permanently deleted “{title}”',
@@ -490,7 +518,7 @@ window.__ModuleLoader__.load({
     /**
      * @param {string} sessionId session whose eligibility to ask for.
      * @param {AbortSignal} [outerSignal] cancellation from the menu occurrence.
-     * @returns {Promise<{ eligible: boolean, code?: string } | null>} the verdict, or null when unknown.
+     * @returns {Promise<{ eligible: boolean, code?: string, message?: string, details?: unknown } | null>} the verdict, or null when unknown.
      */
     async function preflight(sessionId, outerSignal) {
       const controller = new AbortController()
@@ -1526,6 +1554,14 @@ window.__ModuleLoader__.load({
           if (entry.formatStatus === 'migration-required') {
             badges.push({ key: 'migration', label: t('badgeMigration'), tone: 'warn' })
           }
+          const subagentCount = entry.subagentCount ?? 0
+          if (subagentCount > 0) {
+            badges.push({
+              key: 'subagents',
+              label: format(t('badgeSubagents'), { count: subagentCount }),
+              tone: 'info',
+            })
+          }
           const retention = remaining(entry, locale, now)
           if (retention.days !== null && retention.days <= 3) {
             badges.push({
@@ -2019,14 +2055,23 @@ window.__ModuleLoader__.load({
               return
             }
             bumpRevision()
-            const responseTitle = payload !== null && payload !== undefined && payload.entry !== undefined ? payload.entry.title : undefined
+            const responseEntry = payload !== null && payload !== undefined ? payload.entry : undefined
+            const responseTitle = responseEntry !== null && responseEntry !== undefined ? responseEntry.title : undefined
             const title =
               typeof responseTitle === 'string' && responseTitle !== ''
                 ? responseTitle
                 : typeof fallbackTitle === 'string' && fallbackTitle !== ''
                   ? fallbackTitle
                   : sessionId
-            ctx.contextMenus.notify(format(t('trashSuccess'), { title }), true, {
+            const subagentCount =
+              responseEntry !== null && responseEntry !== undefined && typeof responseEntry.subagentCount === 'number'
+                ? responseEntry.subagentCount
+                : 0
+            const message =
+              subagentCount > 0
+                ? format(t('trashSuccessTree'), { title, count: subagentCount })
+                : format(t('trashSuccess'), { title })
+            ctx.contextMenus.notify(message, true, {
               label: t('undo'),
               run: () => undoTrash(sessionId, title),
               failureLabel: t('undoFailed'),
@@ -2153,7 +2198,20 @@ window.__ModuleLoader__.load({
                   }
                 }
                 const verdict = await preflight(sessionId, signal)
-                if (verdict === null || verdict.eligible !== true) return []
+                if (verdict === null) return []
+                if (verdict.eligible !== true) {
+                  const blocked = typeof verdict.code === 'string' ? MOVE_BLOCKED_KEYS[verdict.code] : undefined
+                  if (blocked === undefined) return []
+                  return [
+                    {
+                      id: 'move-refused',
+                      label: t(blocked.label),
+                      icon: { key: MENU_ID },
+                      separatorBefore: true,
+                      run: () => ctx.contextMenus.notify(t(blocked.toast), false),
+                    },
+                  ]
+                }
                 return [
                   {
                     id: 'move',

package/lib/concurrency.js

@@ -0,0 +1,30 @@
+/**
+ * Small concurrency helpers shared by the trash services.
+ *
+ * @module dsh-session-trash/concurrency
+ */
+
+/**
+ * Run `worker` over every item with a bounded number of in-flight operations.
+ * Results keep the input order; the first rejection stops the remaining work and
+ * rejects the returned promise.
+ *
+ * @param {readonly T[]} items input items.
+ * @param {number} limit maximum in-flight operations.
+ * @param {(item: T, index: number) => Promise<R>} worker per-item operation.
+ * @returns {Promise<R[]>} results in input order.
+ * @template T, R
+ */
+export async function mapLimit(items, limit, worker) {
+  const results = new Array(items.length)
+  let next = 0
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) {
+      const index = next
+      next += 1
+      results[index] = await worker(items[index], index)
+    }
+  })
+  await Promise.all(runners)
+  return results
+}

package/lib/eligibility.js

@@ -6,7 +6,9 @@ import { isSafeDirectoryPath } from './fsops.js'
 export const PREFLIGHT_TTL_MS = 2000
 
 /**
- * @typedef {{ eligible: true } | { eligible: false, code: string, message: string, details?: object }} PreflightResult
+ * @typedef {{ sessionId: string, header: object }} DescendantRef
+ * @typedef {{ sessionId: string, header: object, location: { path: string }, formatStatus?: string }} PlannedMember
+ * @typedef {{ eligible: true, members: PlannedMember[] } | { eligible: false, code: string, message: string, details?: object }} PreflightResult
  */
 
 /**
@@ -20,32 +22,33 @@ function refuse(code, message, details) {
 }
 
 /**
- * Collect the ids of every stored session whose lineage descends from `sessionId`.
+ * Collect every stored session whose lineage descends from `sessionId`.
  *
  * @param {import('@deepseek-ai/dsh-session-persistence').SessionPersistence} persistence persistence service.
  * @param {string} sessionId root session.
- * @returns {Promise<string[]>} descendant ids.
+ * @returns {Promise<DescendantRef[]>} descendant identity and stored header.
  */
 async function descendantsFromListing(persistence, sessionId) {
   const snapshots = await persistence.list()
   const childrenByParent = new Map()
   for (const snapshot of snapshots) {
-    const parent = snapshot?.header?.parentSession
-    if (typeof parent !== 'string') continue
+    const header = snapshot?.header
+    const parent = header?.parentSession
+    if (typeof parent !== 'string' || typeof header?.id !== 'string') continue
     const bucket = childrenByParent.get(parent)
-    if (bucket === undefined) childrenByParent.set(parent, [snapshot.header.id])
-    else bucket.push(snapshot.header.id)
+    if (bucket === undefined) childrenByParent.set(parent, [header])
+    else bucket.push(header)
   }
   const found = []
   const queue = [sessionId]
   const visited = new Set([sessionId])
   while (queue.length > 0) {
     const current = queue.shift()
-    for (const child of childrenByParent.get(current) ?? []) {
-      if (visited.has(child)) continue
-      visited.add(child)
-      found.push(child)
-      queue.push(child)
+    for (const header of childrenByParent.get(current) ?? []) {
+      if (visited.has(header.id)) continue
+      visited.add(header.id)
+      found.push({ sessionId: header.id, header })
+      queue.push(header.id)
     }
   }
   return found
@@ -57,24 +60,26 @@ async function descendantsFromListing(persistence, sessionId) {
  * root session owns a lineage the trash must not split.
  *
  * @param {readonly object[]} nodes descendant nodes from the trace.
- * @returns {string[]} every descendant session id.
+ * @returns {DescendantRef[]} every descendant session identity and header.
  */
 function collectTraceDescendants(nodes) {
-  const ids = []
+  const found = []
   const visit = (list) => {
     for (const node of list) {
-      const id = node?.session?.header?.id ?? node?.session?.id
-      if (typeof id === 'string' && id !== '') ids.push(id)
+      const header = node?.session?.header
+      const id = header?.id ?? node?.session?.id
+      if (typeof id === 'string' && id !== '') found.push({ sessionId: id, header: header ?? {} })
       if (Array.isArray(node?.descendants)) visit(node.descendants)
     }
   }
   visit(Array.isArray(nodes) ? nodes : [])
-  return ids
+  return found
 }
 
 /**
- * Decide whether one session may move into the trash. The same predicate backs
- * both the menu preflight and (from Phase 2) the write path.
+ * Decide whether one session may move into the trash. A session that owns only
+ * hidden `origin: 'subagent'` descendants may move together with them; any
+ * other descendant keeps the historical refusal.
  *
  * @param {{ ctx: import('@deepseek-ai/cordis').Context, store: import('./store.js').TrashStore, logger: object }} deps host services.
  * @returns {{ evaluate: (sessionId: string) => Promise<PreflightResult>, invalidate: (sessionId?: string) => void }} the cached evaluator.
@@ -83,6 +88,82 @@ export function createEligibility({ ctx, store, logger }) {
   /** @type {Map<string, { expires: number, value: PreflightResult }>} */
   const cache = new Map()
 
+  /**
+   * @param {string} sessionId session to inspect.
+   * @returns {boolean} whether the session is live in this host process.
+   */
+  function isLive(sessionId) {
+    const liveSession = typeof ctx.sessions?.get === 'function' ? ctx.sessions.get(sessionId) : undefined
+    const liveAgent = typeof ctx.agents?.get === 'function' ? ctx.agents.get(sessionId) : undefined
+    return liveSession !== undefined || liveAgent !== undefined
+  }
+
+  /**
+   * @param {string} sessionId session to inspect.
+   * @returns {Promise<DescendantRef[] | { error: true }>} the complete descendant list, or a refusal marker.
+   */
+  async function collectDescendants(sessionId) {
+    const sessionQuery = ctx.get('sessionQuery')
+    if (sessionQuery !== undefined && sessionQuery !== null && typeof sessionQuery.traceSession === 'function') {
+      try {
+        const trace = await sessionQuery.traceSession(sessionId)
+        return collectTraceDescendants(trace?.descendants ?? [])
+      } catch (error) {
+        logger.warn(`preflight lineage failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`)
+        return { error: true }
+      }
+    }
+    try {
+      return await descendantsFromListing(ctx.sessionPersistence, sessionId)
+    } catch (error) {
+      logger.warn(`preflight lineage listing failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`)
+      return { error: true }
+    }
+  }
+
+  /**
+   * @param {string} sessionId descendant session to validate.
+   * @returns {Promise<object>} either `{ member }` with the planned member or `{ refusal }`.
+   */
+  async function planDescendant(sessionId) {
+    let snapshot
+    try {
+      snapshot = await ctx.sessionPersistence.stat(sessionId)
+    } catch (error) {
+      logger.warn(`preflight stat failed for child session ${sessionId}: ${error instanceof Error ? error.message : String(error)}`)
+      return { refusal: refuse('IO_ERROR', 'A child session in this lineage could not be read.', { sessionId }) }
+    }
+    if (snapshot === undefined || snapshot === null) {
+      return {
+        refusal: refuse('SESSION_NOT_MATERIALIZED', 'A child session has no stored log yet.', { sessionId }),
+      }
+    }
+    const location = snapshot.location
+    if (location === undefined || location === null || typeof location.path !== 'string') {
+      return {
+        refusal: refuse('SESSION_NOT_MATERIALIZED', 'A child session has no stored log yet.', { sessionId }),
+      }
+    }
+    if (location.kind !== 'jsonl') {
+      return {
+        refusal: refuse('STORAGE_UNSUPPORTED', `A child session uses the "${String(location.kind)}" storage backend, which is not supported.`, {
+          sessionId,
+        }),
+      }
+    }
+    if (!path.isAbsolute(location.path)) {
+      return { refusal: refuse('STORAGE_UNSUPPORTED', 'A child session log path is not absolute.', { sessionId }) }
+    }
+    return {
+      member: {
+        sessionId,
+        header: snapshot.header,
+        location: { path: location.path },
+        formatStatus: snapshot.formatStatus,
+      },
+    }
+  }
+
   /**
    * @param {string} sessionId session to inspect.
    * @returns {Promise<PreflightResult>} the uncached verdict.
@@ -125,34 +206,36 @@ export function createEligibility({ ctx, store, logger }) {
       return refuse('SESSION_SUBAGENT', 'Subagent sessions cannot be moved to the trash on their own.')
     }
 
-    let descendants
-    const sessionQuery = ctx.get('sessionQuery')
-    if (sessionQuery !== undefined && typeof sessionQuery.traceSession === 'function') {
-      try {
-        const trace = await sessionQuery.traceSession(sessionId)
-        descendants = collectTraceDescendants(trace?.descendants ?? [])
-      } catch (error) {
-        logger.warn(`preflight lineage failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`)
-        return refuse('SESSION_LINEAGE_UNRESOLVED', 'The session lineage could not be resolved, so the session is left untouched.')
-      }
-    } else {
-      try {
-        descendants = await descendantsFromListing(ctx.sessionPersistence, sessionId)
-      } catch (error) {
-        logger.warn(`preflight lineage listing failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`)
-        return refuse('SESSION_LINEAGE_UNRESOLVED', 'The session lineage could not be resolved, so the session is left untouched.')
-      }
+    const descendants = await collectDescendants(sessionId)
+    if (!Array.isArray(descendants)) {
+      return refuse('SESSION_LINEAGE_UNRESOLVED', 'The session lineage could not be resolved, so the session is left untouched.')
     }
-    const childCount = descendants.filter((id) => typeof id === 'string' && id !== '').length
-    if (childCount > 0) {
+    const visible = descendants.filter((child) => child.header?.origin !== 'subagent')
+    if (visible.length > 0) {
       return refuse('SESSION_HAS_DESCENDANTS', 'This session still has child sessions; archive the tree instead.', {
-        descendants: childCount,
+        descendants: visible.length,
+        sessions: visible.map((child) => child.sessionId),
       })
     }
 
-    const liveSession = typeof ctx.sessions?.get === 'function' ? ctx.sessions.get(sessionId) : undefined
-    const liveAgent = typeof ctx.agents?.get === 'function' ? ctx.agents.get(sessionId) : undefined
-    if (liveSession !== undefined || liveAgent !== undefined) {
+    const planned = []
+    for (const child of descendants) {
+      const plannedChild = await planDescendant(child.sessionId)
+      if (plannedChild.refusal !== undefined) return plannedChild.refusal
+      planned.push(plannedChild.member)
+    }
+
+    const members = [
+      {
+        sessionId,
+        header: snapshot.header,
+        location: { path: location.path },
+        formatStatus: snapshot.formatStatus,
+      },
+      ...planned,
+    ]
+
+    if (isLive(sessionId)) {
       return refuse('SESSION_LIVE', 'This session is open right now. Close it before moving it to the trash.')
     }
 
@@ -169,19 +252,34 @@ export function createEligibility({ ctx, store, logger }) {
       })
     }
 
-    const sessionDir = path.dirname(location.path)
-    let stats
-    try {
-      stats = await fs.lstat(sessionDir)
-    } catch (error) {
-      logger.warn(`preflight cannot stat ${sessionDir}: ${error instanceof Error ? error.message : String(error)}`)
-      return refuse('IO_ERROR', 'The session directory could not be read.')
+    // Running descendants are already reported by the subagent activity
+    // provider; a live-but-idle child is the remaining unsafe case.
+    const liveChild = members.slice(1).find((member) => isLive(member.sessionId))
+    if (liveChild !== undefined) {
+      return refuse('SESSION_LIVE', 'A child session is still live in this host.', {
+        sessionId: liveChild.sessionId,
+      })
     }
-    if (!stats.isDirectory() || !isSafeDirectoryPath(sessionDir)) {
-      return refuse('UNSAFE_SESSION_DIR', 'The session directory is not a plain directory this plugin can move.')
+
+    for (const member of members) {
+      const sessionDir = path.dirname(member.location.path)
+      let stats
+      try {
+        stats = await fs.lstat(sessionDir)
+      } catch (error) {
+        logger.warn(`preflight cannot stat ${sessionDir}: ${error instanceof Error ? error.message : String(error)}`)
+        return refuse('IO_ERROR', 'A session directory could not be read.', {
+          ...(member.sessionId === sessionId ? {} : { sessionId: member.sessionId }),
+        })
+      }
+      if (!stats.isDirectory() || !isSafeDirectoryPath(sessionDir)) {
+        return refuse('UNSAFE_SESSION_DIR', 'A session directory is not a plain directory this plugin can move.', {
+          ...(member.sessionId === sessionId ? {} : { sessionId: member.sessionId }),
+        })
+      }
     }
 
-    return { eligible: true }
+    return { eligible: true, members }
   }
 
   return {