dsh-sessions-manager 3.7.6 → 3.7.8

package/src/client/logic.js

@@ -221,6 +221,26 @@ export function noticeToastPlan(raw, seenIds, max = 2) {
   }
 }
 
+// issue #18 第 1 条：把「父会话不在当前列表」的子代理从顶层行里摘出来。
+//
+// foldSubagents 只收「父在列表里」的子代理；其余子代理原先留在顶层平铺成
+// 一行行「(无标题)」，一个多代理工作日能攒出上百行。这里把它们分成一组，
+// 调用方渲染成一张可展开的卡片——不污染列表，也不丢会话。
+// 输入应为 foldBranches 之后的 topList（分支聚拢不会碰子代理）。
+export function foldOrphanSubagents(items, lineage) {
+  const list = Array.isArray(items) ? items : []
+  const table = lineage && typeof lineage === 'object' ? lineage : {}
+  const rows = []
+  const orphans = []
+  for (const it of list) {
+    const id = it && it.sessionId != null ? String(it.sessionId) : ''
+    const info = id ? table[id] : null
+    if (info && info.origin === 'subagent') orphans.push(it)
+    else rows.push(it)
+  }
+  return { rows, orphans }
+}
+
 // —— T3（3.7.0）：分支聚拢 ——
 // 把「同一父会话派生出的普通分支会话」归组，收拢到组锚（真实父行或合成头）
 // 之下。子代理已由 foldSubagents 先行摘除，本函数只处理非子代理的分支血缘。
@@ -462,3 +482,116 @@ export function filterShapeFromSaved(item) {
   if (tag === '' && f.tag !== '') degraded.push('tag')
   return { view, workspace, sort, tag, degraded }
 }
+
+// issue #16：侧栏「展开其余 N 个会话」的 N 由上游按**数据层**计算
+// （0.2.0-rc.2 `collapsedSessionRows` → 0.2.1-rc.2 `watermarkRows`），
+// 看不到插件用 display:none 隐藏的回收站/空白行，于是数字虚高；点展开只是
+// 把更多已隐藏行塞进 DOM，可见行数不变——按钮在动、画面不动，容易被误读成
+// 「会话丢了」。
+//
+// 注意**不能**用「N − 本组被插件隐藏的条数」：上游的 N 数是「水位线之外
+// 还没渲染的行」，隐藏数数的是「整组被藏起来的行」，两个口径不重叠——被藏的
+// 行可能就在已渲染窗口内，减它属重复扣减，点开一次就翻负，进而把仍有可见行
+// 的按钮藏掉（上游只有这一个展开入口 → 会话不可达）。
+//
+// 正确口径由 `remainingRows` 给出：还能出现几行 = 本组可见总数 − 已渲染的
+// 可见行数；`overflowPlan` 只负责把它写进文案、并决定是否藏按钮。
+export function remainingRows(visibleTotal, renderedVisible) {
+  // Number(null) === 0：null / undefined 必须当作「不知道」，不能当成 0。
+  if (visibleTotal == null || visibleTotal === '') return null
+  const total = Number(visibleTotal)
+  if (!Number.isFinite(total)) return null
+  const shown = Number(renderedVisible)
+  const shownCount = Number.isFinite(shown) ? Math.max(0, Math.floor(shown)) : 0
+  return Math.max(0, Math.max(0, Math.floor(total)) - shownCount)
+}
+
+// 折叠分组的「还能出现几行」（issue #16 的第二个分支）。
+//
+// 上游 `group.sessions` 只在展开时才有内容（`expanded ? [...].map(...) : []`），
+// 而展开按钮恰恰只在折叠时出现 —— 也就是说「拿不到成员 id」与「需要校准计数」
+// 同时发生。折叠态改用两条与展开无关的信息：
+//   groupCount  上游 `group.sessionCount`，组内会话总数（已过 sessionVisible）
+//   trashInGroup 本工作区的回收站条数（host 按 cwd 统计后下发）
+// 展开后实际会出现的行数 = groupCount − trashInGroup；折叠时 DOM 里没有会话行，
+// 已渲染可见数按 0 计。
+//
+// 任一输入拿不到（老 host 没有该字段 / group 没有 cwd）就返回 null —— 调用方
+// 据此保持上游原文案，绝不猜一个可能错位的数字。
+export function collapsedVisibleTotal(groupCount, trashInGroup) {
+  if (groupCount == null || trashInGroup == null) return null
+  const total = Number(groupCount)
+  const trash = Number(trashInGroup)
+  if (!Number.isFinite(total) || !Number.isFinite(trash)) return null
+  return Math.max(0, Math.floor(total) - Math.max(0, Math.floor(trash)))
+}
+
+// 本组已渲染的可见会话行数。`rows` 是直接子节点里会话行的描述
+// （{ id, pluginHidden }），`visibleIds` 是「上游会列出且插件不会藏」的 id 集合。
+// 插件隐藏的行（回收站 / 空白）与不在集合里的行（空白会话 / 上游过滤口径差异）
+// 都不计入 —— 与 `remainingRows` 的「可见总数」保持同一口径。
+export function countRenderedVisible(rows, visibleIds) {
+  if (!Array.isArray(rows) || !visibleIds || typeof visibleIds.has !== 'function') return 0
+  let n = 0
+  for (const row of rows) {
+    if (!row || row.pluginHidden) continue
+    if (row.id && visibleIds.has(row.id)) n++
+  }
+  return n
+}
+
+// 空分组判定：`group.sessions` 里「还会出现在侧栏」的条数。
+// - 空白会话不计：上游 `watermarkRows` 里 `if (session.blank) return true`，
+//   空白行永远保留、从不计入可展开数；插件也一律把它藏起来。
+// - `hiddenIds` = 回收站 / 墓碑 / 空白血缘的行 id（与展开计数同一份口径）。
+// - 返回 null 表示**不知道**（拿不到数据层，或该组还没加载出会话）：调用方
+//   必须按「非空」处理——宁可留一个空标题，也不能把仍有会话的组藏掉。
+export function aliveSessionCount(sessions, hiddenIds) {
+  if (!Array.isArray(sessions) || !sessions.length) return null
+  let alive = 0
+  let seen = 0
+  for (const node of sessions) {
+    if (!node || node.id == null) continue
+    const id = String(node.id)
+    if (!id) continue
+    seen++
+    if (node.blank) continue
+    if (hiddenIds && typeof hiddenIds.has === 'function' && hiddenIds.has(id)) continue
+    alive++
+  }
+  // 一条带 id 的都没有 = 结构不认识（不是「组空」），照未知处理。
+  return seen === 0 ? null : alive
+}
+
+// 把「还能出现几行」落到展开按钮上：
+// - `more` 未知（拿不到数据层）→ 一律不动作。DOM 兜底在数学上不成立
+//   （窗口内/外的隐藏数口径不同），宁可不改也不写一个看起来合理却会算错的数；
+// - 文案没有数字（展开态的「收起」、或上游改成纯图标）→ 不改也不藏。无法确认
+//   是不是计数文案时保持沉默；
+// - 只替换第一个数字（各语言文案都把计数放在数字位，如「展开其余 12 个会话」
+//   /「Show 12 more」），支持千分位写法；
+// - `more === 0` 才藏按钮：此时确实一行都不会再出现，留着只会让人反复点。
+export function overflowPlan(text, more) {
+  const raw = typeof text === 'string' ? text : ''
+  const unknown = more == null || !Number.isFinite(Number(more))
+  const remaining = unknown ? 0 : Math.max(0, Math.floor(Number(more)))
+  const m = raw.match(/(\d[\d,]*)/)
+  const base = m ? Number(m[1].replace(/,/g, '')) : null
+  if (base === null || unknown) {
+    return { text: raw, hide: false, base, more: unknown ? null : remaining, changed: false }
+  }
+  if (remaining === 0) {
+    // base<=0 是上游没给出可信计数（理论上不会出现）：不据此隐藏，避免误判。
+    return { text: raw, hide: base > 0, base, more: 0, changed: false }
+  }
+  if (remaining === base) {
+    return { text: raw, hide: false, base, more: remaining, changed: false }
+  }
+  return {
+    text: raw.slice(0, m.index) + String(remaining) + raw.slice(m.index + m[1].length),
+    hide: false,
+    base,
+    more: remaining,
+    changed: true,
+  }
+}

package/src/index.js

@@ -29,7 +29,7 @@ import { createPersistenceAdapter } from './compat/persistence.js'
 import { detectCapabilities, requireCapability } from './compat/capabilities.js'
 import { pathOwnsSession } from './path-guard.js'
 import { purgeSessionArtifacts, moveSessionToCwd } from './handle-era-ops.js'
-import { classifyLineage, emptyScanCandidate, isEmptyEventTypes, EMPTY_DECODE_LIMIT } from './lineage.js'
+import { classifyLineage, emptyScanCandidate, isEmptyEventTypes, subagentDescendantsOf, EMPTY_DECODE_LIMIT } from './lineage.js'
 
 // 构建指纹：build.mjs 以 define 在编译期注入；直接以源码运行（测试）时为 'dev'。
 // 用途：capabilities 带出 buildStamp，一眼判断「运行中的 host 是不是这份构建」——
@@ -669,7 +669,7 @@ export function apply(ctx) {
   // it from the workspace) orphaned the session into DSH's "未分组" group and
   // made restore land in 未分组 instead of the original workspace — so we leave
   // the file where it is and let the sidebar DOM shim hide the row instead.
-  async function deleteOne(sid) {
+  async function deleteOne(sid, opts = {}) {
     requireSessionId(sid)
     // Soft-delete is always allowed — including the currently-active conversation.
     // The log file stays in its original workspace dir (recorded in the 回收站
@@ -682,7 +682,9 @@ export function apply(ctx) {
     let removedPath = null
     let persistenceEntry = null
     try {
-      const entries = await persistence.listEntries()
+      // 级联删除时由调用方传入同一份 listEntries 快照：一个父会话带上 N 个子代理
+      // 时不重复扫盘（issue #18 第 4 条）。
+      const entries = Array.isArray(opts.entries) ? opts.entries : await persistence.listEntries()
       const found = entries.find((entry) => entry.id === sid) || null
       persistenceEntry = found
       header = found ? found.header : null
@@ -726,6 +728,9 @@ export function apply(ctx) {
         sizeBytes: persistenceEntry && Number.isFinite(persistenceEntry.sizeBytes) ? persistenceEntry.sizeBytes : null,
         wasArchived: archived, deletedAt: Date.now(),
       }
+      // 跟随父会话一起回收的子代理：记住来源，恢复/彻底删除父会话时按它级联
+      // （用户单独删除的子代理没有这个字段，不会被父会话的恢复带着走）。
+      if (opts.cascadeFrom) entry.cascadeFrom = String(opts.cascadeFrom)
       const at = store.items.findIndex((t) => String(t.sessionId) === sid)
       if (at >= 0) store.items[at] = entry
       else store.items.push(entry)
@@ -734,6 +739,77 @@ export function apply(ctx) {
     return { ok: true, trashed: true }
   }
 
+  // issue #18 第 4 条：子代理会话的生命周期跟随父会话。
+  //
+  // 用户反馈「删除父会话，子代理会遗留在活动会话中，污染列表」——先前删除只处理
+  // 传入的那一个 id，子代理成了无父孤儿。这里按官方 header 的 origin/parentSession
+  // 收集后代（零解码，复用同一个 listEntries 快照），父会话删除时一并回收。
+  //
+  // 只走官方字段，且有步数上限与 visited 防环；任何异常都退回「只删父会话」，
+  // 绝不因为血缘表坏掉而拒绝删除。判定本身是纯函数（lineage.js），单测覆盖。
+  function subagentDescendantIdsFrom(entries, rootId) {
+    const headers = []
+    for (const entry of Array.isArray(entries) ? entries : []) {
+      if (entry && entry.header) headers.push(entry.header)
+    }
+    // live 会话可能还没进 listEntries 快照，但它不会有「已落盘的后代」缺失问题；
+    // 已持久化的子代理都在 entries 里，所以这里只走快照，避免重复扫描。
+    return subagentDescendantsOf(headers, rootId)
+  }
+
+  // 删除一个会话 +（可选）它的子代理后代。返回 cascaded 数量供 UI 如实提示。
+  async function deleteWithSubagents(sid, opts = {}) {
+    let entries = Array.isArray(opts.entries) ? opts.entries : null
+    if (!entries) {
+      try { entries = await persistence.listEntries() } catch (e) { entries = null }
+    }
+    const out = await deleteOne(sid, { entries })
+    const cascade = opts.cascade !== false
+    if (!cascade || !entries) return { ...out, cascaded: 0, cascadedIds: [] }
+    const kids = subagentDescendantIdsFrom(entries, sid)
+    // 已经在回收站里的子代理不再碰：它可能是用户**单独**删掉的，重新写一遍会把
+    // 它的删除时间与来源改成「跟随父会话」，此后恢复父会话就会把它带回来——
+    // 与「用户自己删的不会被带走」的承诺相反。跳过即保留它原来的删除语义。
+    let alreadyTrashed = null
+    try {
+      const store = await readTrashStore()
+      alreadyTrashed = new Set(store.items.map((t) => String(t.sessionId)))
+    } catch (e) { alreadyTrashed = null }
+    const cascadedIds = []
+    for (const kid of kids) {
+      if (alreadyTrashed && alreadyTrashed.has(String(kid))) continue
+      try {
+        await deleteOne(kid, { entries, cascadeFrom: sid })
+        metaCache.invalidate(kid)
+        cascadedIds.push(kid)
+      } catch (e) { /* 单个子代理失败不拖垮整次删除 */ }
+    }
+    return { ...out, cascaded: cascadedIds.length, cascadedIds }
+  }
+
+  // 与删除对称：恢复 / 彻底删除父会话时，把它连带回收的子代理一并处理。
+  // 只认 entry.cascadeFrom（用户单独删掉的子代理没有该字段，不会被带走），
+  // 且只在回收站里找——父会话恢复后子代理不会留在回收站里变成孤儿。
+  async function cascadeTrashChildren(sid, op) {
+    let kids = []
+    try {
+      const store = await readTrashStore()
+      kids = store.items
+        .filter((t) => String(t.cascadeFrom || '') === String(sid))
+        .map((t) => String(t.sessionId))
+    } catch (e) { return [] }
+    const results = []
+    for (const kid of kids) {
+      try {
+        results.push({ sessionId: kid, ok: true, ...(await op(kid)) })
+        metaCache.invalidate(kid)
+      } catch (e) {
+        results.push({ sessionId: kid, ok: false, error: String((e && e.message) || e) })
+      }
+    }
+    return results
+  }
+
   // 恢复前的底层校验（0.1.3 契约下 restoreIndexedSession 不再无条件可用）：
   //   1. 底层 stored session 仍存在（live / stat / list 三级判定）；
   //   2. 日志文件仍在原处（软删除不动文件，originalPath 丢失即外部破坏）；
@@ -1729,6 +1805,18 @@ export function apply(ctx) {
     const payload = {
       titles: Object.fromEntries(authorityTitleCache),
       trashedSessionIds: store.items.map((item) => String(item.sessionId)),
+      // issue #16：回收站按 cwd 的条数。折叠分组下上游把 group.sessions 收回成
+      // 空数组，client 拿不到成员 id，只能用「组内会话总数 − 本组回收站条数」
+      // 还原展开按钮该显示的数字；有了这份统计，那次扣减才是准确的而非估算。
+      trashedCountByCwd: (() => {
+        const acc = {}
+        for (const item of store.items) {
+          const cwd = typeof item.cwd === 'string' ? item.cwd : ''
+          if (!cwd) continue
+          acc[cwd] = (acc[cwd] || 0) + 1
+        }
+        return acc
+      })(),
       purgedSessionIds: activeTombstones,
       lineage,
       // v3.6.2：还有预热/退避重试在途 → client 缩短轮询节拍，预热一完成就把
@@ -1795,11 +1883,30 @@ export function apply(ctx) {
         const persistBatch = {}
         for (const [id, desc] of batch) {
           try {
-            const types = []
+            // issue #18 第 5 条：只收事件类型会把「插件注入上下文」的会话误判成
+            // 有内容。`agent/inbox/spliced` 需要看插入项来源，这里只留判定所需的
+            // 最小信息（source 对象 + removedCount），绝不把消息正文带进内存。
+            const events = []
             await persistence.inspectSession(id, { onEvents: (b) => {
-              for (const ev of b || []) if (types.length < 64) types.push(ev && ev.type)
+              for (const ev of b || []) {
+                if (events.length >= 64) break
+                if (!ev) { events.push(undefined); continue }
+                if (ev.type !== 'agent/inbox/spliced') { events.push({ type: ev.type }); continue }
+                const data = ev.data && typeof ev.data === 'object' ? ev.data : null
+                events.push({
+                  type: ev.type,
+                  data: data
+                    ? {
+                        removedCount: data.removedCount,
+                        inserted: Array.isArray(data.inserted)
+                          ? data.inserted.map((m) => ({ source: m && typeof m === 'object' ? m.source : null }))
+                          : null,
+                      }
+                    : null,
+                })
+              }
             } })
-            const isEmpty = isEmptyEventTypes(types)
+            const isEmpty = isEmptyEventTypes(events)
             emptyScanCache.set(id, { sizeBytes: desc.sizeBytes, empty: isEmpty })
             persistBatch[id] = { empty: isEmpty ? 1 : 0, fingerprint: `sz:${desc.sizeBytes}`, updatedAt: Date.now() }
           } catch (e) {
@@ -2072,7 +2179,9 @@ export function apply(ctx) {
           const body = await readJsonBody(req)
           const sid = body && typeof body.sessionId === 'string' ? body.sessionId : null
           if (!sid) return json(res, { ok: false, error: 'missing sessionId' }, 400)
-          const out = await deleteOne(sid)
+          // issue #18 第 4 条：默认连带子代理一起回收（cascadeSubagents:false 可保留
+          // 子代理——它们在面板里会落进「未归属子代理」卡片，仍可管理）。
+          const out = await deleteWithSubagents(sid, { cascade: body.cascadeSubagents !== false })
           // 日志被搬进回收站（文件已不在原处）：丢弃缓存条目，避免下次 stat 失败
           // 时残留旧元数据。
           metaCache.invalidate(sid)
@@ -2092,11 +2201,24 @@ export function apply(ctx) {
           const ids = parseIds(body)
           if (!ids || ids.length === 0) return json(res, { ok: false, error: 'missing sessionIds' }, 400)
           const results = []
+          // 级联与单删一致：一次快照，多个父会话的子代理不会互相重复回收。
+          let cascadeEntries = null
+          try { cascadeEntries = await persistence.listEntries() } catch (e) { cascadeEntries = null }
+          const cascade = body.cascadeSubagents !== false
+          const done = new Set()
           for (const sid of ids) {
-            try { results.push({ sessionId: sid, ok: true, ...(await deleteOne(sid)) }); metaCache.invalidate(sid) }
-            catch (e) { results.push({ sessionId: sid, ok: false, error: String((e && e.message) || e) }) }
+            try {
+              if (done.has(sid)) { results.push({ sessionId: sid, ok: true, trashed: true, cascaded: 0 }); continue }
+              const out = cascade && cascadeEntries
+                ? await deleteWithSubagents(sid, { cascade: true, entries: cascadeEntries })
+                : await deleteOne(sid, { entries: cascadeEntries })
+              done.add(sid)
+              if (Array.isArray(out.cascadedIds)) for (const k of out.cascadedIds) done.add(k)
+              results.push({ sessionId: sid, ok: true, ...out })
+              metaCache.invalidate(sid)
+            } catch (e) { results.push({ sessionId: sid, ok: false, error: String((e && e.message) || e) }) }
           }
-          json(res, { ok: true, deleted: results.filter((r) => r.ok).length, results })
+          json(res, { ok: true, deleted: results.filter((r) => r.ok).length, cascaded: results.reduce((n, r) => n + (Number(r.cascaded) || 0), 0), results })
         } catch (e) {
           json(res, { ok: false, code: e && e.code, error: String((e && e.message) || e) }, errorStatus(e))
         }
@@ -2172,7 +2294,9 @@ export function apply(ctx) {
           if (!sid) return json(res, { ok: false, error: 'missing sessionId' }, 400)
           const out = await restoreFromTrash(sid)
           metaCache.invalidate(sid)
-          json(res, out)
+          // 连带回收的子代理一起回来，父子生命周期保持一致。
+          const cascaded = await cascadeTrashChildren(sid, (kid) => restoreFromTrash(kid))
+          json(res, { ...out, cascaded: cascaded.filter((r) => r.ok).length, cascadedResults: cascaded.length ? cascaded : undefined })
         } catch (e) {
           json(res, { ok: false, code: e && e.code, error: String((e && e.message) || e) }, errorStatus(e))
         }
@@ -2192,7 +2316,14 @@ export function apply(ctx) {
           // 彻底删除：持久标题索引里的条目一并清掉（issue #1 P4）。
           try { await titleIndex.remove([sid]) } catch (e) { /* 索引清理失败不阻塞删除结果 */ }
             try { await emptyIndex.remove([sid]) } catch (e) { /* 同上 */ }
-          json(res, out)
+          // 连带回收的子代理一并物理删除（否则父会话消失、子代理孤零零留在回收站）。
+          const cascaded = await cascadeTrashChildren(sid, async (kid) => {
+            const r = await purgeFromTrash(kid)
+            try { await titleIndex.remove([kid]) } catch (e) {}
+            try { await emptyIndex.remove([kid]) } catch (e) {}
+            return r
+          })
+          json(res, { ...out, cascaded: cascaded.filter((r) => r.ok).length })
         } catch (e) {
           json(res, { ok: false, code: e && e.code, error: String((e && e.message) || e) }, errorStatus(e))
         }
@@ -2209,8 +2340,19 @@ export function apply(ctx) {
           if (!ids || ids.length === 0) return json(res, { ok: false, error: 'missing sessionIds' }, 400)
           const results = []
           for (const sid of ids) {
-            try { results.push({ sessionId: sid, ok: true, ...(await purgeFromTrash(sid)) }); metaCache.invalidate(sid); await titleIndex.remove([sid]).catch(() => {}); await emptyIndex.remove([sid]).catch(() => {}) }
-            catch (e) { results.push({ sessionId: sid, ok: false, error: String((e && e.message) || e) }) }
+            try {
+              results.push({ sessionId: sid, ok: true, ...(await purgeFromTrash(sid)) })
+              metaCache.invalidate(sid)
+              await titleIndex.remove([sid]).catch(() => {})
+              await emptyIndex.remove([sid]).catch(() => {})
+              // 与单条彻底删除一致：连带回收的子代理一并清掉。
+              await cascadeTrashChildren(sid, async (kid) => {
+                const r = await purgeFromTrash(kid)
+                try { await titleIndex.remove([kid]) } catch (e) {}
+                try { await emptyIndex.remove([kid]) } catch (e) {}
+                return r
+              })
+            } catch (e) { results.push({ sessionId: sid, ok: false, error: String((e && e.message) || e) }) }
           }
           json(res, { ok: true, purged: results.filter((r) => r.ok).length, results })
         } catch (e) {

package/src/lineage.js

@@ -45,15 +45,52 @@ const LIFECYCLE_EVENT_TYPES = new Set([
   'approval/policy',
 ])
 
+// 注入型事件：`agent/inbox/spliced` 把消息写进下一轮的 inbox。它不是用户输入，
+// 但它**可能**是插件塞进来的上下文/指令（issue #18 第 5 条：openviking-memory
+// 之类的记忆插件会这么干）。这种会话在界面上空空如也，先前却被算作「有内容」
+// → 永远进不了「空白」分类，只能一直占着列表。
+//
+// 判定按「插入项来源」做，而不是按事件类型一刀切——真实用户消息同样走这个
+// 事件，绝不能连人打的字一起判空：
+//   - 每条插入消息都带 source，且 source.form === 'instructions' 或
+//     source.kind 以 'plugin:' 开头 → 纯注入，算噪声；
+//   - 有任何一条没有 source / 是普通用户消息 → 算内容；
+//   - 同时带 removedCount（删了东西）→ 算内容（可能删掉了真实消息）。
+function isInjectedMessage(msg) {
+  const src = msg && typeof msg === 'object' ? msg.source : null
+  if (!src || typeof src !== 'object') return false
+  if (src.form === 'instructions') return true
+  return typeof src.kind === 'string' && src.kind.startsWith('plugin:')
+}
+
+// 单条事件是否属于「不构成内容」的噪声。接受两种形状：
+//   - 旧形状：事件类型字符串（向后兼容，历史调用点与单测仍这样传）
+//   - 新形状：{ type, data } —— 只有 inbox 注入需要看 data
+export function isNoiseEvent(event) {
+  const type = typeof event === 'string' ? event : event && typeof event === 'object' ? event.type : null
+  if (typeof type !== 'string') return false
+  if (LIFECYCLE_EVENT_TYPES.has(type)) return true
+  if (type !== 'agent/inbox/spliced') return false
+  const data = event && typeof event === 'object' ? event.data : null
+  if (!data || typeof data !== 'object') return false
+  const removed = Number(data.removedCount)
+  if (Number.isFinite(removed) && removed > 0) return false
+  // inserted 缺失/畸形一律按内容处理（宁可漏判，不可错杀）。
+  if (!Array.isArray(data.inserted)) return false
+  if (data.inserted.length === 0) return true
+  return data.inserted.every(isInjectedMessage)
+}
+
 /**
- * @param {Array<string|undefined>} types 事件类型序列（不含头部也可，含头部
- *        也可——'session' 在放行清单里）。0 条 = 头部之外无任何事件，视为空。
+ * @param {Array<string|{type?:string,data?:object}|undefined>} events 事件序列
+ *        （类型字符串或带 data 的事件对象；不含头部也可，含头部也可——
+ *        'session' 在放行清单里）。0 条 = 头部之外无任何事件，视为空。
  * @returns {boolean}
  */
-export function isEmptyEventTypes(types) {
-  if (!Array.isArray(types)) return false
-  for (const t of types) {
-    if (typeof t !== 'string' || !LIFECYCLE_EVENT_TYPES.has(t)) return false
+export function isEmptyEventTypes(events) {
+  if (!Array.isArray(events)) return false
+  for (const ev of events) {
+    if (!isNoiseEvent(ev)) return false
   }
   return true
 }
@@ -62,6 +99,49 @@ export function isEmptyEventTypes(types) {
 // subagent or a fork branch; `empty` is published as null (= not yet judged)
 // and refined in the background. Ordinary top-level sessions return null —
 // they only ever gain an entry once a real decode says empty:true.
+export const SUBAGENT_CASCADE_LIMIT = 500
+
+/**
+ * 子代理后代（issue #18 第 4 条：子代理生命周期跟随父会话）。
+ *
+ * 只认官方 header 的 `origin === 'subagent'` + `parentSession`，零解码：
+ * 删除父会话时由宿主把同一份 listEntries 快照传进来，一次扫描算出整棵子树。
+ *
+ * @param {Array<object>} headers 会话 header 列表（可为 null / 含畸形项）
+ * @param {string} rootId 父会话 id
+ * @param {number} [limit] 节点上限（默认 SUBAGENT_CASCADE_LIMIT，防病态血缘）
+ * @returns {string[]} 后代 id（广度优先，含孙代；不含 rootId 自身）
+ */
+export function subagentDescendantsOf(headers, rootId, limit = SUBAGENT_CASCADE_LIMIT) {
+  const root = rootId == null ? '' : String(rootId)
+  if (!root) return []
+  const kidsOf = new Map()
+  for (const h of Array.isArray(headers) ? headers : []) {
+    if (!h || typeof h !== 'object' || h.id == null || h.origin !== 'subagent') continue
+    const id = String(h.id)
+    const parent = h.parentSession != null ? String(h.parentSession) : ''
+    // 自指 / 空父一律跳过：它们不构成「后代」边。
+    if (!parent || parent === id) continue
+    if (!kidsOf.has(parent)) kidsOf.set(parent, [])
+    kidsOf.get(parent).push(id)
+  }
+  const max = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : SUBAGENT_CASCADE_LIMIT
+  const out = []
+  const visited = new Set([root])
+  const queue = [root]
+  while (queue.length && out.length < max) {
+    const cur = queue.shift()
+    for (const kid of kidsOf.get(cur) || []) {
+      if (visited.has(kid)) continue
+      visited.add(kid)
+      out.push(kid)
+      queue.push(kid)
+      if (out.length >= max) break
+    }
+  }
+  return out
+}
+
 export function classifyLineage(header) {
   if (!header || typeof header !== 'object') return null
   const origin = header.origin === 'subagent' ? 'subagent' : null