[Bug] 回归：0.2.0-rc.2 起，删除子代理会话目录不再从 UI 清除该条目

[ExplorerZYzhou]

EN TL;DR: After 0.2.0-rc.2, deleting a subagent's session directory no longer removes it from the Web UI — the record now lives as a subagent/catalog event in the parent session log, and there is no retire/removal path in the event, projection, query, or tool layer. The same release added a full archive lifecycle for sessions (unarchiveSession). Request: give subagent records a symmetric "retire" capability.

---

摘要

#1202 记录过"子代理条目无法从 UI 清除"，并指出当时唯一的办法是手工删除磁盘上的会话目录——该办法有效。

0.2.0-rc.2（2026-09-30 升级）之后，这个办法失效了：删除子代理的会话目录不再影响 UI 显示，帖子会一直留在子代理列表里（"一次性 · 当前未运行"），刷新与重启均无效。

原因：子代理记录现在是父会话日志里的 subagent/catalog 事件，而事件层、投影层、查询层、工具层四层都没有移除或退役路径。也就是说，从"有手工变通办法但没有一等公民入口"，退化成了"完全没有任何办法"。

而同一次升级为会话补齐了 unarchiveSession（完整归档生命周期：归档 → 视图筛选 → 取消归档 → 撤销）——这正好回应了 #1202 评论区当时提出的"归档会不可逆、得按不可逆动作设计"的顾虑。因此本贴请求的是为子代理记录补上对称的那一半，而不是从零发明某个能力。

---

既有报告（本贴的增量在哪）

相邻讨论已有两条，但它们定位在状态层，本贴定位在记录层——互补，不是重复。

#476（已关闭 · resolved）

[bug] Subagent sessions that did not terminate normally are shown as green (ready/archived state indistinguishable from completed)

诊断的是状态显示：约 39 个子代理会话处于 ready 状态（仅存在于存储、可 send_message 续接、非终态），却在 UI 中被渲染成绿色 done，与真正完成的无法区分。

它给出了最底层的成因（注意这句直接支持我们的论点）：

packages/subagent/subagent/src/cli/list-children.ts（49-55 行）JSDoc：
"Store snapshot activity: running means the logical record is live in ctx.sessions; inactive means it exists only in persistence. Neither encodes a durable outcome, and a continuable child may still reject delivery as an ownership conflict."

以及 GUI 侧的取色分支（ui-subagent/.../SubagentCatalogAction.tsx:348）：

<StateDot state={entry.activity === 'running' ? 'ongoing' : 'done'} />
//                    ↑ running→蓝         ↑ 一切非 running→绿（done）

#1202（仍然开启 · 1 条评论）

[Bug][Web GUI] Failed subagents stay visible in the UI as if still running — non-terminal ready state, no way to clear them from the UI

环境 0.1.0-rc.6 / Linux。诊断的是状态机：后台子代理已失败，UI 却仍显示为运行中；list_agents 报 ready（非终态）。

它的第二条诉求是"提供一个 dismiss 动作"，且正文明确记录了当时的变通办法：

"There is no way to remove these failed subagent entries from the UI. The only way they disappeared was manually deleting their session directories on disk (~/.dsh/sessions/<project>/<session-id>/)."

—— 这就是本贴的切入点：那个唯一办法，在 0.2.0-rc.2 上不再生效。

#1202 的评论（weijiafufu14, Aug 27）—— 与本贴最有关系的两点

(a) 它把三帖归纳为"一个缺失字段的三种表现"：同一个 ready 在 #476/#478 被渲染成绿色"已完成"，在 #1202 被渲染成"仍在活动"，而 list_agents 报的 ready 才是真实语义（但只有工具能看到）。建议把诉求从"请把失败的标成失败"提到"activity 需要能表达终态结局"。

(b) 它列了一张 DSH 公开 API 表，回答"能否提供清除动作"：

动作	它当时的结论（Aug 27）	本贴核对（0.2.0-rc.2）
归档一个会话	✅ workspaceRegistry.archiveSession(sessionId)	✅ 仍在
取消归档 / 恢复	❌ 没有 unarchive 等对等方法	✅ 已补上 unarchiveSession(sessionId)
永久删除会话日志	❌ SessionPersistence 无 delete / forget	❌ 仍未提供

并给出警告："它只是只增操作：归档了就没有官方的取消归档路径。所以如果做成用户可点的按钮，得当一个不可逆动作来设计（至少要有确认）"。

—— 0.2.0-rc.2 恰恰为会话解决了这个"不可逆"顾虑（取消归档 + 三态筛选 + 归档提示的撤销动作）。这就是本贴"对称性"论据的来源：同样的顾虑，官方已经为会话解了一次，子代理这一次还没有。

本贴与它们的区别

	#476 / #1202	本贴
层面	状态层：状态机非终态 / activity 无法表达终态结局	记录层：subagent/catalog 事件成为父会话日志中的不可变事实
触发条件	子代理非正常终止（failed）	子代理正常完成也会发生——UI 已正确显示"当前未运行"，条目依然无法移除
可清除性	"没有一等公民入口，但删目录的变通办法有效"	变通办法失效：同一操作在 8 月有效、10 月无效（行为回归）
问题的性质	状态语义缺失（缺字段）	生命周期缺失（缺退役路径）+ 回归

一句话：#476 / #1202 解决的是"为什么它看起来还活着"；本贴解决的是"为什么它明明结束了却删不掉"。

本贴的三点增量

增量	说明
① 打断既有变通办法（最强）	#1202 赖以清除条目的"手工删目录"在 0.2.0-rc.2 失效，问题从"有变通办法"退化为"完全无解"。附完整 UUID 与时间戳，可逐条核验
② 新机制定位	指明根因：subagent/catalog 事件 + subagentCatalog 投影，并给出四层（事件 / 投影 / 查询 / 工具）各自缺什么、该在哪一层补
③ 对称性论据	同一次升级已为会话补齐完整归档生命周期，也回应了 #1202 评论提出的"不可逆"顾虑；子代理缺的是对应的另一半

建议：本贴独立提交（根因层面与触发条件都与它们不同，并入会让讨论失焦），正文已引用 #476 / #1202；同时在 #1202 下留一条简短的跟进评论，指出其"唯一办法"已失效并链接本贴——因为那句话现在已经是错的。

---

环境

项	值
@deepseek-ai/dsh	0.2.0-rc.2（Windows）
相关包	@deepseek-ai/dsh-subagent（包内文件时间戳 2026-09-30 15:56:18）
会话日志格式	v4（session.v4.jsonl.zstd）
复现位置	Web GUI 会话头部的子代理列表

---

复现步骤

1. 在任一会话中创建一个子代理（subagent 工具，或 workflow 内的 agent()）。
2. 记下 GUI 顶部的"N 个子智能体"计数。
3. 删除该子代理的会话目录（即 [Bug][Web GUI] Failed subagents stay visible in the UI as if still running — non-terminal ready state, no way to clear them from the UI #1202 正文记录的那个办法）：

   ~/.dsh/sessions/<projectKey>/<childUuid>/
   

4. 刷新 GUI（或重启 DSH）。

实际结果：条目仍在，计数不变。
期望结果：条目消失，或至少提供一个显式的退役/隐藏入口。

对照实验（本贴的核心证据）：同一操作在 2026-09-30 之前的版本上有效——删完 UI 立即清空。实测 8 月共 5 次、共 10 个子代理目录，全部有效；10 月同一批操作全部失效。见「证据链」③。

也就是说：#1202 在当时（0.1.0-rc.6）能靠这一步收场，在 0.2.0-rc.2 上不行了。

---

根因

1. 数据源从"磁盘扫描"改成了"父会话日志投影"

• 9/30 之前：创建子代理只产生磁盘上的会话目录，父会话日志不记录。UI 通过扫描会话目录列出子代理 → 删目录即从列表消失（这是实现方式的副产品，不是正式功能）。
• 9/30 之后：创建子代理时，父会话会追加一条 subagent/catalog 事件。UI 改为读取父会话的 subagentCatalog 投影 → 删目录不影响该事件，记录永久保留。

2. 四层都没有移除语义

层	位置	现状
事件层	dsh-subagent	只有 subagent/catalog 一种事件，无"退役/删除"变体
投影层	subagentCatalogProjectionDefinition	apply 只做 appendChunkedList；view 遍历全部、无存活过滤
查询层	listChildren()	直接返回投影值，不校验子会话是否仍存在
工具层	dsh-tool-subagent-control	只注册 send_message 与 interrupt_agent

（代码摘录见下方折叠块。）

关键代码摘录

投影定义 —— 只有 append，没有移除分支（dsh-subagent/lib/types/catalog.js）：

export const subagentCatalogProjectionDefinition = {
    key: 'subagentCatalog',
    apply: (state, event) => {
        if (event.type !== 'subagent/catalog' || event.seq < state.inheritedEventCount) return state;
        return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) };
        //                                                                    ↑ 只有 append
    },
    wire: { view: subagentCatalogEntries },
};

function subagentCatalogEntries(state) {
    const entries = [];
    for (const data of iterateChunkedList(state.head)) {
        entries.push({ id: data.childId, createdAt: data.childCreatedAt, mode: data.mode, ...label });
    }
    return entries;   // ← 直接返回，不检查子会话是否仍存在
}

UI 数据源（dsh-subagent/lib/types/list-children.js）：

export async function listChildren(ctx, parentSessionId, signal) {
    const parent = await query.observeSession(parentSessionId, { signal });
    return parent.projections?.values.subagentCatalog;   // ← 只读投影
}

工具层（dsh-tool-subagent-control/lib/index.js）：

name: "send_message"
name: "interrupt_agent"
// 无删除 / 退役工具

父会话日志中的实际记录：

{
  "type": "subagent/catalog",
  "seq": 6517,
  "time": 1791739054872,
  "data": {
    "version": 0,
    "childId": "7334292e-0892-44eb-81a9-4d305ca51fa6",
    "childCreatedAt": 1791739054844,
    "mode": "one-shot",
    "label": "Casual subagent probe"
  }
}

---

证据链

① subagent/catalog 只出现在 v4 格式文件中

会话（真实 UUID）	v1/v3 文件	v4 文件
session-fad4189f-64f2-423f-9bf3-34224ea101a0	0 条（但 v3 期间有 13 次 workflow 子代理调用）	1 条
session-1550a353-006e-4ee7-8153-4fa761599637	0 条（但 v3 期间有 13 次 workflow 子代理调用）	4 条

两者同属 projectKey --F-deepseek~0020~0020harness--。

② 同一会话、同一工具，相隔 52 天行为不同（关键对照）

会话 session-1550a353-006e-4ee7-8153-4fa761599637：

时间	工具	subagent/catalog	事件 seq
2026-08-20 10:50	workflow	❌ 无	（tool/call seq 5481）
2026-10-11 17:00:09	workflow	✅ 有	12164
2026-10-11 17:00:55	workflow	✅ 有	12211
2026-10-11 17:01:17	workflow	✅ 有	12230
2026-10-11 17:04:24	workflow	✅ 有	12274

（catalog 事件与对应 tool/call 相隔 0.3–0.4 秒，确认为同一次 spawn 产生。）

③ 清理记录对撞

时间	删除的子代理目录（完整 UUID）	UI 结果
2026-08-19 15:35	8e452f5a-d80e-4758-b17b-61178db41adf、f1d55623-59d9-4017-826b-0d35fe2b9900、86e92bfd-eaf9-4892-b0ce-e9ed9cea2d32	✅ 清空
2026-08-20 10:27	d761831b-f416-4d28-87ed-84fa36d41d5c、207cba51-c581-4825-a5e4-ef521abfbf33	✅ 清空
2026-08-28 14:54	70daeb5d-bfa9-495b-a871-f94f05fa85ae、fbce292e-4db3-4e03-b6e3-a99b83c378b8	✅ 清空
2026-08-28 15:18	0063bb9c-3b60-429d-bc60-309c323e41e2	✅ 清空
2026-08-28 15:55	2a8a7860-3c57-41a7-b8cd-25256ad18e58、b9f17d8c-567c-4d41-80ed-45bf8c0d921e	✅ 清空
2026-10-11 17:09	d14b24e8-43af-486a-b69e-f73b3d11ca5b、1dea3837-09cb-4540-acb3-cb5d302e661b、d37a3d83-626b-44ef-81e8-ec076fd28e62、29556e75-05d2-407d-a8c8-5fc23a682c39	❌ 仍显示
2026-10-11 17:18	7334292e-0892-44eb-81a9-4d305ca51fa6	❌ 仍显示

关键对撞：10-11 17:09 删除的 4 个 UUID，与 ② 中同日 17:00–17:04 产生的 4 条 catalog 事件的 childId 完全一致；而 8 月那 5 次清理（当时无 catalog 事件）全部有效。即：同一批 UUID，删掉后 8 月有效、10 月无效。

④ 包文件时间戳

dsh-subagent/lib/types/catalog.js
  CreationTime  : 2026/9/30 15:56:18
  LastWriteTime : 2026/9/30 15:56:18

---

修复建议

方案 A（推荐，符合现有 append-only 架构）
为 catalog 引入追加式退役语义：新增 subagent/retire 事件（记录 childId、原因、时间），subagentCatalogProjectionDefinition 折叠时将其标记为 retired，subagentCatalogEntries 过滤掉 retired 条目。日志仍完整留痕，UI 可清理。

方案 B（最小改动，但语义较弱）
subagentCatalogEntries / UI 层过滤掉"子会话已不存在于 session store"的条目。缺点是把"记录是否显示"重新绑定到磁盘存在性，与 9/30 那次改进的方向（不依赖磁盘扫描）相悖。

方案 C（补入口）
增加 forget_subagent 工具（配合方案 A 的事件），让用户或 agent 显式退役子代理记录。

无论采用哪种，建议在文档中明确"子代理记录的生命周期"，避免用户继续按"删目录"的旧习惯操作。

---

一致性论据（本贴的核心）

0.2.0-rc.2 已经为会话补齐了完整的归档生命周期：

能力	实现
宿主 API	dsh-workspace 暴露 unarchiveSession(sessionId): Promise<void>
客户端入口	会话行菜单「取消归档」(order 400)、行 hover 按钮 (order 100)、搜索结果恢复按钮、归档提示的撤销动作
视图筛选	三态：隐藏归档（默认）/ 全部会话（显示归档）/ 仅归档
运行中归档	「停止并归档」确认框，按家族列出进行中的 turn、子代理、后台任务、定时提醒
README 约束	从 "No Session deletion or unarchive control" 收窄为 "No Session deletion"

而同一次升级（引入 v4 日志格式与 subagent/catalog）让子代理记录只有"登记"没有"退役"。

因此本问题不宜被归类为"DSH 不做破坏性入口"的设计取舍——更准确的定性是生命周期不完整的一致性缺口：会话有"归档 ↔ 取消归档"，子代理只有 catalog 登记。既然官方愿意为会话提供减法入口，子代理缺的对应一半也应当补齐。

---

影响

1. 用户侧能力回归：原本次代理可清理，升级后不可清理，且无替代入口。
2. 列表永久累积：每个历史子代理都会长期占据 GUI 空间。
3. 附带：~/.dsh/storages/session_projcache/sessions/<childUuid>.json 在删除子代理目录后不会清理，实测已堆积多个已删子代理的缓存文件（纯缓存，不影响 UI）。

---

相关讨论

相邻层面（子代理条目的状态与清除）—— 本贴的直接上下文：

• [Bug][Web GUI] Failed subagents stay visible in the UI as if still running — non-terminal ready state, no way to clear them from the UI #1202（开启，1 条评论）— Failed subagents stay visible in the UI as if still running — non-terminal ready state, no way to clear them from the UI
  • 正文记录了"唯一办法 = 手工删磁盘目录"，该办法在 0.2.0-rc.2 已失效
  • 评论（weijiafufu14, Aug 27）给出 DSH 公开 API 表，并警告归档会是"只增操作、不可逆"
• [bug] Subagent sessions that did not terminate normally are shown as green (ready/archived state indistinguishable from completed) #476（已关闭 · resolved）— Subagent sessions that did not terminate normally are shown as green (ready/archived state indistinguishable from completed)
  • 定位状态—颜色映射；引出关键源码注释 "Neither encodes a durable outcome"（list-children.ts:49-55）
• [bug] Subagent sessions orphaned by a force-killed harness restart shown as green — no interruption marker, indistinguishable from completed #478 — [Bug][Web GUI] Failed subagents stay visible in the UI as if still running — non-terminal ready state, no way to clear them from the UI #1202 中列为同源：同一 ready 状态被渲染为绿色 "completed"

（以上定位"状态层"；本贴定位"记录层"，区别见「既有报告」节。）

同一类（缺少减法入口）：

• #4741 — Session management UX gaps: ungrouped sessions can't be moved, cross-workspace sessions invisible, no UI delete
• #40 — archived sessions cannot be viewed or restored（该条已于 0.2.0-rc.2 解决：unarchiveSession 已内建，见「一致性论据」节）

同版本 / 同 UI 区域：

• #8459 — Desktop 0.2.0-rc.2: expanding the "ungrouped" sessions section crashes the renderer
• #1557 — 侧边栏"未分组"行显示无效的"新建会话"加号按钮（同一区域，本人提交）

指引与背景：

• #1797 — Welcome to DeepSeek Harness Community（置顶指引帖）
• dshbase《DeepSeek Harness Community Bug Report》（2026-08-14，通读 321 条社区 bug 讨论的第三方归纳）

---

附注

• 本贴所有 session 与 child UUID 均为实测原始值，官方可对照本地 ~/.dsh/sessions/ 与 session.v4.jsonl.zstd 直接核验；事件 seq 与毫秒时间戳同样为原始值。
• projectKey --F-deepseek~0020~0020harness-- 中的 ~0020~ 是空格转义（本地工作区路径含空格），仅用于定位，不含敏感信息。
• 复现所需的一切都在本地数据目录内，不涉及任何私有服务或凭证。

[argszero]

The record layer is append-only, and that is why nothing else in the product can clear it

Your layer analysis matches the source. The parent-side record is a projection over an append-only fold — packages/subagent/subagent/src/catalog.ts:

apply: (state, event: SessionEvent) => {
  if (event.type !== 'subagent/catalog' || event.seq < state.inheritedEventCount) return state
  return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) }
},

and the wire view maps every collected entry to a row:

function subagentCatalogEntries(state) {
  for (const data of iterateChunkedList(state.head)) { ... entries.push({ id: childId, createdAt: childCreatedAt, ...descriptor }) }
}

There is no counterpart to appendChunkedList here, and the apply function ignores any event type other than subagent/catalog — so a new event appended by anyone (a plugin included) cannot remove a row; the only writer of that row is this fold. The README states the same as intent, not as an oversight: "Catalog entries record membership once at creation and carry no execution status."

Deleting the child's session directory therefore cannot work any more, and the reason is upstream of the UI: the row is derived from the parent's log, and the child directory is not an input to it. Two consequences worth naming:

• unarchiveSession is not the symmetric counterpart here. The archive lifecycle lives on the session record; the subagent catalog has no state field to flip — the row exists iff the fold saw a subagent/catalog event, so the missing capability is a retire/tombstone event plus a fold that honours it, not a session-state transition.
• A plugin cannot supply it either. A client-half plugin could hide the row when rendering (display only — the child session still exists, still counts, still appears to any other reader), and a plugin appending a new event type would be ignored by the fold above. This one needs the event and all three consumers of it.

So the request is right and it is a small one in shape: one version bump of the catalog payload with a terminal flag (or a sibling subagent/retire fact), the fold dropping retired ids, and the query/tool layers following. Bonus: the same tombstone would fix the older #1202 complaint, since "dismiss" would finally be expressible without touching disk.

[ExplorerZYzhou]

Thanks — and the correction lands. Let me concede the weak half of my own argument first.

"unarchiveSession is the missing symmetric counterpart" was wrong, for exactly the reason you give: it flips a state field on the session record, while this row has no state field to flip — it exists iff the fold saw a subagent/catalog event. What should be asked for is the shape you describe: a retire/tombstone fact plus a fold that honours it, with the query and tool layers following. (That is option A in my write-up; I just hung it on an analogy that does not hold.)

Re-tested on the released 0.2.1-rc.2

I have since moved off the version I filed this on and re-ran the experiment end-to-end on 0.2.1-rc.2, so this is no longer only source reading:

• Spawned a fresh subagent → parent appended subagent/catalog (seq 8219, mode: continuable).
• Deleted that child's session directory from disk entirely (Test-Path → false; the single 16 KB log file gone).
• Refreshed the UI: the row is still there. The counter reads 2, with zero subagent directories on disk.
• I also went through the UI looking for any dismissal affordance on those rows. There is none — no clear/retire/remove action anywhere on the subagent list.

The older record behaves the same way: its catalog event (seq 6517, mode: one-shot, label "Casual subagent probe") is still listed although its directory was deleted on 2026-10-11, thirteen days ago.

Two things this added beyond the source reading:

1. A failed child still leaves a row. The fresh subagent failed before finishing ("failed before it finished"), and the catalog entry persisted regardless — which matches the README sentence you quoted: entries "carry no execution status."
2. The stateVersion bump did refold and the rows survived. catalog went from stateVersion: 3 in the release I filed against to 6 now, so the projection cache was rebuilt from the log — and since no subagent/catalog event was removed, every row came back. That is the append-only property doing exactly what it promises, in the direction that hurts here.

So the record layer is unchanged between the version I filed against and 0.2.1-rc.2. What has changed is the status layer: master (and 0.2.1) now registers subagentTiming alongside subagentCatalog, and its fold sets lastTurnCompleted = event.data.reason.kind === 'completed' — which is the first half of #1202's complaint, answered. That makes the split concrete: the status layer is being filled in; the record layer still has no way to express retirement. (Which also refines your bonus note slightly: the tombstone would fix #1202's second request — an expressible dismiss — since its first is now covered by subagentTiming.)

Two questions

1. Can the projection definition be replaced under the same key? i.e. could a host-half plugin register subagentCatalog with a higher stateVersion and an apply that also honours a new event type, rather than waiting for core? If the registry permits it, this is fixable out-of-core today; if not, your "the event and all three consumers of it" is exact and core is the only path. You write plugins against this seam; I only read it.

2. After retire, should the row disappear from subagentCatalogEntries, or stay with a retired marker? The second keeps "this child existed" queryable, which feels closer to how every other durable fact in this harness is treated — and it would also let the UI distinguish "retired" from "never existed".

Thanks again for checking the fold rather than the UI. That is what made the answer land, and it shaped how I re-ran the test.