fix: stabilize session list and Codex imports

.planning/sidebar-title-refresh-storm/findings.md

@@ -0,0 +1,114 @@
+# 调研记录：侧栏标题刷新风暴
+
+## 用户现象
+
+- 问题偶发，子代理较多、运行中会话集中时出现。
+- 标题/会话列表区域持续刷新重绘，期间无法可靠点击。
+- 一段时间后会自行恢复。
+
+## 截图观察
+
+- 侧栏同时展示多个“运行中”会话，项目分组数量较多。
+- DevTools 中 `.session-list` 包含大量 `.session-project-group` 节点，多数处于 `collapsed` 状态。
+- 问题区域是会话/项目分组列表，不是消息正文。
+
+## 当前假设
+
+- 高频会话或子代理状态事件触发了侧栏全量渲染。
+- 全量渲染替换点击目标节点，导致 `mousedown` 与 `click` 期间节点身份变化，表现为“点不了”。
+- 需要区分事件风暴、无变化数据重复发布、前端缺少合并，以及 DOM 全量重建四类可能原因。
+- 用户明确提醒“子代理多”只是猜测；后续必须用调用频率、数据变化和节点身份等证据独立验证，不能按该猜测定向修复。
+
+## 项目初始化发现
+
+- Trellis 开发者身份已存在：`shiyue`。
+- 当前 Trellis 任务指向旧的 `07-17-gilded-wasteland-theme`，与本次侧栏刷新问题不一致；开始实现前需确认其状态并避免把本次产物混入旧任务。
+- 项目为单仓库，规范层包含 `frontend` 与 `backend`；本问题预计优先读取前端规范。
+
+## 代码索引初查
+
+- `codebase-memory-mcp` 项目 `home-cc-web` 已就绪：4203 个节点、9129 条边。
+- 侧栏列表核心入口命中 `public/app.js` 的 `renderSessionList`（索引行 8640–8750），入度为 8，说明存在多个调用来源。
+- 该函数可见代码会为置顶分组和普通项目分组重新 `document.createElement('section')` 并追加到 `sessionList`；是否每次调用都先清空列表、是否全部调用都需要重建，仍需读取完整源码和入站调用链确认。
+- 检索结果也命中已弃用的 `graphify-out` 噪声；后续不使用其产物，继续按项目约定只使用代码索引和源码校验。
+
+## 已确认的渲染行为
+
+- `renderSessionList()` 第一行执行 `sessionList.innerHTML = ''`，随后重新创建全部置顶分组、项目分组、会话项及事件监听器；因此每次调用都会替换整个侧栏列表节点树。
+- 入站调用者至少有 8 个：`applySessionSnapshot`、`handleServerMessage`、`syncViewForAgent`、`openSession`、`setProjectCollapsed`、`applySessionPinnedState` 等。
+- 这已经证实“节点会被整体替换”，但尚未证实哪个调用源形成高频触发；下一步需要检查会话快照和服务器消息处理是否在数据未变化时仍调用渲染。
+- 需要关注的交互机制是：全量替换如果发生在指针按下与抬起之间，浏览器不会把它识别为对原按钮的有效点击。这能解释现象，但仍需事件链证据完成根因闭环。
+
+## 前端消息触发点
+
+- 收到每一条 `session_list` 都会无条件替换 `sessions` 并调用 `renderSessionList()`，没有内容相等或列表视图签名判断。
+- 收到每一条 `session_message` 后也会调用 `renderSessionList()`；该路径会处理当前会话和跨会话消息。
+- `session_renamed`、置顶变化、项目折叠、搜索输入等也会调用，但这些通常是低频交互，暂时不是“持续一段时间后恢复”的首要嫌疑。
+- 流式 `text_delta` 与 `content_blocks` 只调度消息区渲染，不直接刷新侧栏，因此不能简单把所有模型流式输出都归因于侧栏重绘。
+- 下一步必须追踪服务端 `session_list` / `session_message` 的发布频率与触发条件，并检查子代理状态更新是否会间接生成这些事件。
+
+## 服务端会话列表发布链路
+
+- `sendSessionList(ws)` 每次都会同步扫描会话目录、读取所有会话元数据、排序并发送完整 `session_list`；它本身没有去重或节流。
+- `broadcastSessionList()` 会遍历所有已连接客户端，并为每个客户端重新执行一次完整会话扫描和发送。
+- `broadcastSessionList` 有 13 个直接调用入口，除标题、置顶、跨会话消息外，明确包含 `sendCcwebMcpChildAgentUpdate`。
+- `sendSessionList` 还有 15 个直接调用入口，包括普通消息、Codex App 消息、turn 完成、进程完成等。
+- 这说明子代理更新确实可能放大会话列表推送，但它只是候选链路之一；需要继续检查 `sendCcwebMcpChildAgentUpdate` 的调用频率、是否每个增量都广播，以及现场运行日志/浏览器计数。
+
+## 子代理更新链路证据
+
+- `syncCcwebMcpChildAgentsFromCollabItem()` 会对每个接收线程更新 child 状态，并在循环内调用 `sendCcwebMcpChildAgentUpdate()`。
+- `sendCcwebMcpChildAgentUpdate()` 先向当前会话发送局部 `ccweb_mcp_child_agent_update`，随后**无条件**调用 `broadcastSessionList()`。
+- 因此一次包含多个 receiver thread 的协作事件会在同一循环中多次广播完整会话列表；每次广播又会让每个浏览器客户端重新扫描服务端全部会话文件，并让前端整段替换侧栏 DOM。
+- 前端对局部 `ccweb_mcp_child_agent_update` 只更新工具卡和缓存，本身不刷新侧栏；造成侧栏重建的是其后附带的完整 `session_list` 广播。
+- 这条链路与用户描述吻合，但仍需验证现场事件量，以及非子代理来源是否也能形成同等频率的完整列表推送。
+
+## 可见数据变化与历史背景
+
+- 每次 child 增量都会经 `updatePersistedCcwebMcpChildTool()` 把父会话的 `session.updated` 改为当前时间并保存整份会话；因此完整 `session_list` 的载荷确实每次不同，简单做“完整 JSON 相等去重”无法挡住这类刷新。
+- 会话项真正渲染的字段包括标题、运行/未读/等待状态、置顶、项目信息以及相对更新时间；更新时间只是其中唯一在每个 child 增量必变的侧栏字段。
+- `waitingOnChildren` 来自跨会话回复队列，不来自 MCP child-agent 状态；因此仅为了 child 工具卡进度而广播完整列表，并不是更新该等待徽标所必需。
+- Git 追溯显示这条“child 更新后无条件广播列表”的实现自 2026-06-16 的 Codex App 集成改动起存在，并非本轮临时改动。
+- 现有回归覆盖 child 工具卡路由与 V2 `subAgentActivity`，尚未覆盖侧栏节点稳定性或重复完整列表刷新。
+
+## 修复方向候选
+
+- 服务端只移除 child 更新后的列表广播：成本低，但无法防住普通 `session_message`、其他重复 `session_list` 等来源。
+- 前端只做延迟/节流：能降频，但连续事件期间仍会周期性替换点击目标，不能从机制上保证可点击。
+- 前端基于“影响布局与交互的视图签名”跳过结构相同的全量重建，并仅原位更新时间文本：可保留节点身份；当会话顺序、标题、状态、分组、搜索或折叠状态变化时仍正常重建。当前优先推荐此方案，并考虑同时删除明显冗余的 child 列表广播。
+
+## 计划审查结论
+
+- 独立计划审查已通过，无阻塞问题。
+- 回归测试需明确验证高频状态更新期间项目分组节点身份稳定、点击能力不丢失，不能只比较最终 DOM 文本。
+
+## 待补充
+
+- 当前环境没有 Chromium、Playwright 或 Puppeteer，真实浏览器交互降级为最小 DOM 行为回归；该回归已验证清空次数从纯更新时间每次 +1 降为保持不变，并验证项目组/会话项对象身份与点击监听器不变。
+- 部署后再观察运行态 CPU 与 HTTP 延迟；修改尚未重启前不能把旧进程指标误当作新实现指标。
+
+## 规范与任务上下文
+
+- 已建立独立 Trellis 任务 `07-30-sidebar-title-refresh-storm`，未结束或归档原有旧主题任务。
+- 前端规范文件目前多数仍是占位模板；实现需主要遵循仓库现有 vanilla JS 模式、回归脚本模式和本任务 PRD。
+- PRD 明确不移除协议广播，而在前端渲染边界区分结构变化与纯时间变化，以覆盖子代理和普通消息等同类来源。
+
+## 最终实现
+
+- `buildSessionListStructureSignature()` 对已完成排序、分组、折叠/旧会话拆分后的渲染模型生成签名。
+- 签名排除原始 `updated`，但纳入排序后的可见/隐藏会话顺序、标题、项目、置顶、运行、未读、等待、当前会话、搜索与折叠状态；因此纯时间变化不重建，时间造成排序/可见性变化时仍会重建。
+- `refreshSessionListRelativeTimes()` 在签名相同时按 `data-id` 原位更新 `.session-item-time`，不会替换项目分组、会话项或监听器。
+- 回归使用最小 DOM stub 实际执行两次渲染，验证清空次数、节点对象身份、点击监听器、时间文本，以及标题/状态/顺序变化后的重建。
+- 初版回归的 `splitCollapsedSessions()` stub 永远不返回隐藏会话，漏掉了 `createOldSessionLoadMoreButton()` 分支，导致 `oldSessionCollapseKey` 漏解构未被发现；现已加入真实隐藏会话场景并先复现同一错误。
+- `public/index.html` 的 app/style 缓存版本已更新为 `20260730-sidebar-title-refresh-storm`，避免浏览器继续复用含该错误的旧脚本。
+- `updatePersistedCcwebMcpChildTool()` 对同一父会话的 running 增量做 250ms 尾随合并；冲刷前重新加载最新父会话并重放每个 child 的最新状态，避免覆盖父 turn 同期写入。
+- `scheduleCcwebMcpChildSessionListBroadcast()` 合并 child 引起的全量列表广播；`returned`、`failed`、`interrupted`、`closed` 会立即保存并广播。
+- 局部 `ccweb_mcp_child_agent_update` 仍对每个增量立即发送，工具卡实时性不受批处理影响。
+
+## 最终审查与运行态
+
+- 独立最终审查通过，无新的阻塞问题。
+- 结构签名现在只在空态或完整 DOM 成功渲染后提交；部分渲染异常后的下一次快照会重新构建，而不是接受半成品 DOM。
+- pending child 状态按 `threadId || spawnToolId` 分别保存，同一可见工具下的 sibling/nested child 不再互相覆盖。
+- 当前进程未再次重启：仓库要求重启前先确认没有其他运行中的对话，但本轮重启后该会话列表工具未重新注入，因此保守保留现有在线进程。
+- 前端静态资源已通过新缓存版本在线提供；服务进程当前已加载此前重启前的批处理实现，最新 sibling key 变更待下一次安全重启后加载。

.planning/sidebar-title-refresh-storm/progress.md

@@ -0,0 +1,90 @@
+# 进度记录：侧栏标题刷新风暴
+
+## 会话：2026-07-30
+
+### 阶段 1：确认索引与侧栏更新链路
+
+- **状态：** complete
+- **开始时间：** 2026-07-30 15:25 +08:00
+- 已完成：
+  - 阅读用户截图并记录视觉现象。
+  - 扫描并启用 `planning-with-files` 与 `todo-list-csv` 技能。
+  - 执行会话恢复检查，未发现未同步上下文。
+  - 完成 Trellis 会话初始化检查，发现当前任务仍指向一项旧主题任务。
+  - 将用户关于“不要按猜测调查”的约束写入调研记录。
+  - 计划文档通过独立子代理审查。
+  - 确认 `home-cc-web` 代码索引就绪，初步定位 `renderSessionList`。
+  - 读取 `renderSessionList` 完整源码并追踪入站调用，确认每次调用都会清空并重建整个列表。
+  - 核验 `handleServerMessage`：`session_list` 与 `session_message` 均会无条件全量重建侧栏，流式文本事件不会直接重建。
+  - 追踪服务端列表发布链路：完整列表无去重/节流，且子代理状态更新是广播入口之一。
+  - 建立子代理更新闭环：每个 child 增量都会无条件广播完整 `session_list`，前端随后整段替换侧栏。
+  - 确认 child 增量每次都会改写父会话 `updated`，所以完整载荷去重不足；现有测试也未覆盖节点身份稳定性。
+
+### 阶段 2：复现并定位高频重绘根因
+
+- **状态：** complete
+- **开始时间：** 2026-07-30T07:35:21.137Z
+- 下一步：
+  - 已通过代码调用链确认子代理与普通消息均可能触发全量替换。
+  - 已确认服务运行指标正常，排除服务进程阻塞。
+
+### 阶段 3：回归测试与修复
+
+- **状态：** complete
+- **开始时间：** 2026-07-30T07:43:47.002Z
+- 已完成：
+  - 创建独立 Trellis 任务、PRD、根因研究文件及 implement/check 上下文。
+  - 新增 DOM 级失败回归，旧实现按预期失败于“仅 updated 变化仍清空列表”。
+  - 新增结构签名缓存和相对时间原位刷新，实现节点身份与点击监听器稳定。
+  - 新增服务端失败回归，旧实现缺少 child 更新合并并会逐次保存、逐次广播完整列表。
+  - 同一父会话 250ms 内复用待保存快照，尾随冲刷前重读最新会话；最终态立即保存。
+  - 合并 child 引起的完整列表广播，同时保留每次局部工具卡 WebSocket 更新。
+
+### 阶段 4：验证与交付
+
+- **状态：** complete
+- **开始时间：** 2026-07-30T08:10:22.442Z
+- 已完成：
+  - 定向侧栏刷新回归通过。
+  - 侧栏折叠、会话工具提示、子代理卡片路由回归通过。
+  - `public/app.js` 与 `scripts/regression.js` 语法检查通过。
+  - `git diff --check` 通过。
+  - 完整 `npm run regression` 在 60 秒超时约束内通过。
+  - 服务端 child 更新合并定向回归通过，既有子代理卡片路由回归通过。
+  - 用户重启后暴露 `oldSessionCollapseKey` 漏解构；新增历史会话折叠分支回归先复现同一 ReferenceError，再补回字段。
+  - 更新前端静态资源缓存版本；从运行中的 HTTP 服务确认新 index 与修复后的 app.js 已生效。
+  - 修正后定向回归、语法检查、diff 检查与 60 秒完整回归再次通过。
+  - 最终独立 diff 审查通过，确认签名提交时机、sibling child 保留、缓存版本号和未定义变量均无阻塞问题。
+  - 重启后的运行态观察：ccweb 同一 PID 在线，CPU 约 0.6%，连续 HTTP 200 约 0.9–5.8ms；未读取敏感环境配置。
+- 下一步：
+  - 无；服务端后续重启需先确认除当前对话外没有其他 running 对话。
+- 创建文件：
+  - `.planning/sidebar-title-refresh-storm/task_plan.md`
+  - `.planning/sidebar-title-refresh-storm/findings.md`
+  - `.planning/sidebar-title-refresh-storm/progress.md`
+
+## 测试结果
+
+| 测试 | 预期 | 实际 | 状态 |
+|---|---|---|---|
+| 失败回归（修复前） | 仅 updated 变化不应再次清空 | 缺少结构签名/旧实现再次清空 | 预期失败 |
+| 服务端失败回归（修复前） | child 突发合并保存与完整列表广播 | 缺少 `isFinalCcwebMcpChildStatus` 及批处理实现 | 预期失败 |
+| 侧栏刷新定向回归 | 节点稳定且真实结构变化重建 | 通过 | ✓ |
+| child 更新合并回归 | 3 次局部推送、1 次保存、1 次完整列表广播，最终态立即落盘 | 通过 | ✓ |
+| 历史会话折叠失败回归 | 隐藏会话存在时应保留折叠键并正常渲染 | 修复前复现同一 ReferenceError；修复后通过 | ✓ |
+| 部分渲染失败恢复回归 | 首轮异常后再次渲染必须重建完整置顶/项目 DOM | 修复前失败；签名延后提交后通过 | ✓ |
+| 共享 spawnToolId sibling 回归 | 同一工具下多个 child 最终状态都落盘 | 修复前第一个 sibling 丢失；按 threadId 去重后通过 | ✓ |
+| 相关定向回归 | 折叠、提示、子代理路由无回退 | 通过 | ✓ |
+| JS 语法与 diff 检查 | `server.js`、`public/app.js`、`scripts/regression.js` 无语法/空白错误 | 通过 | ✓ |
+| 完整 regression | 全量回归通过 | Regression checks passed | ✓ |
+
+## 错误日志
+
+| 时间 | 错误 | 次数 | 处理 |
+|---|---|---:|---|
+| 2026-07-30T07:49:41.008Z | 误用执行单元等待接口 | 6 | 切换到 `collaboration.wait_agent`；实现任务未受影响 |
+| 2026-07-30T07:49:41.008Z | 错误日志补丁再次因动态时间上下文不匹配 | 1 | 改为匹配稳定表头追加 |
+| 2026-07-30T07:44:54.498Z | full-history fork 不能同时覆盖为 worker 角色 | 1 | 改用 `fork_turns: none`，通过磁盘 PRD 和 JSONL 注入完整上下文 |
+| 2026-07-30T07:46:30.649Z | Default 模式下 `request_user_input` 不可用 | 1 | 不需要用户输入，停止调用并继续实现 |
+| 2026-07-30T07:46:30.649Z | 错误日志补丁的动态时间上下文不匹配 | 1 | 读取稳定尾部后重新追加，未重复原失败补丁 |
+| 2026-07-30T16:45:00+08:00 | `renderSessionList` 漏解构 `oldSessionCollapseKey`，用户重启后前台 ReferenceError | 1 | 新增实际隐藏会话分支回归复现，补回解构并更新缓存版本，完整回归通过 |

.planning/sidebar-title-refresh-storm/task_plan.md

@@ -0,0 +1,56 @@
+# 任务计划：修复侧栏标题刷新风暴
+
+## 目标
+
+定位并修复子代理活跃时侧栏会话标题区域频繁刷新重绘、暂时无法点击的问题，同时建立可重复的回归验证。
+
+## 当前阶段
+
+阶段 4：验证与交付
+
+## 阶段
+
+### 阶段 1：确认索引与侧栏更新链路
+- [x] 确认代码索引状态
+- [x] 定位侧栏列表渲染、会话状态事件和子代理更新入口
+- **状态：** complete
+
+### 阶段 2：复现并定位高频重绘根因
+- [x] 建立事件到 DOM 更新的调用链
+- [x] 确认是否存在全量重建、重复事件或无效状态更新
+- **状态：** complete
+
+### 阶段 3：回归测试与修复
+- [x] 先编写能覆盖状态更新风暴的回归测试
+- [x] 实施最小且可维护的修复
+- **状态：** complete
+
+### 阶段 4：验证与交付
+- [ ] 运行相关单元测试、静态检查与构建
+- [ ] 进行浏览器交互和性能验证
+- [ ] 审查变更并整理结论
+- **状态：** in_progress
+
+## 关键问题
+
+1. 哪类子代理/会话事件会触发侧栏刷新，频率和生命周期如何？
+2. 侧栏是否使用 `innerHTML` 或等价方式重建全部项目分组？
+3. 是否能在不牺牲实时状态的前提下保持节点身份和点击稳定性？
+
+## 已作决策
+
+| 决策 | 理由 |
+|---|---|
+| 优先验证状态更新风暴与全量 DOM 重建的组合问题 | 用户描述与截图均指向运行会话密集时的短时高频重绘 |
+| 先补回归测试再改实现 | 该问题偶发，必须把触发条件固化成可重复检查 |
+| 使用结构视图签名并原位更新时间 | 保留节点身份，同时不牺牲真正的顺序、标题和状态更新 |
+
+## 遇到的错误
+
+| 错误 | 次数 | 处理 |
+|---|---:|---|
+| 多次误把代理等待当成执行单元等待 | 20+ | 后续停止通用轮询，改用代理主动结果、共享工作区变更与正确协作接口 |
+| 错误日志再次使用动态时间作补丁上下文 | 1 | 改为只匹配稳定表头追加记录 |
+| 使用 full-history fork 同时指定 worker 角色被运行时拒绝 | 1 | 改为无历史 fork，并在任务提示中要求读取 Trellis PRD、上下文和项目规范 |
+| Default 模式误调用引导输入工具 | 1 | 本任务不需要用户选择，停止调用并继续既定实现流程 |
+| 记录错误时使用了变化后的动态时间导致补丁上下文不匹配 | 1 | 先读取文件尾部，再基于稳定行追加记录 |