feat: overhaul task board and cross-conversation workflows

.planning/.active_plan

@@ -1 +1 @@
-file-preview-encoding
+2026-08-11-help

.planning/2026-08-11-ccweb-list-children-scope/findings.md

@@ -0,0 +1,73 @@
+# 发现与决策：ccweb_list_conversations children scope
+
+## 需求
+
+- 给 `ccweb_list_conversations` 增加 `scope: "children"`。
+- 同步更新该 MCP 的提示词/描述。
+- 完成实现、回归覆盖和验证。
+
+## 已知代码事实
+
+- `listConversationSummaries(args, sourceSessionId)` 当前遍历 `SESSIONS_DIR` 下全部 JSON，只按 agent/status 过滤，最后排序并应用 limit。
+- MCP 创建的子会话在自身 JSON 中持久化 `createdFrom.kind = "mcp"` 和 `createdFrom.sourceSessionId`。
+- `loadSessionMetaFromFile` 当前只暴露 `createdFromKind`，没有暴露来源会话 ID；实现 children 过滤需扩展元数据或读取完整会话。
+- `ccweb_list_conversations` 有两处 schema/描述：`lib/ccweb-mcp-server.js` 与 `server.js` 的 Codex App 动态工具兼容定义。
+- README 的 MCP 表格需要同步新语义。
+- 当前工作树已有其他任务修改 `server.js`、`lib/ccweb-mcp-server.js`、`scripts/regression.js`，补丁必须基于当前内容最小追加。
+- 本地 `git diff -G` 未发现既有未提交改动触碰 `ccweb_list_conversations`、`listConversationSummaries`、`loadSessionMetaFromFile` 或 `createdFromKind` 相关行；目标区域可做局部补丁。
+- 当前回归先在 `scripts/regression.js` 约 6021 行测试全量列表，MCP 创建及 `createdFrom` 断言位于约 6139 行后，适合在创建完成后追加 children scope 场景。
+- `createdFrom` 已包含在大文件头尾 preview 的顶层字段集合中，因此只需从现有对象提取 `sourceSessionId`，无需为 children scope 全量读取大 JSON。
+- `loadSessionMetaFromFile` 的完整解析和 preview 两条分支都应新增内部字段 `createdFromSourceSessionId`；该字段只用于过滤，不必暴露到 MCP 返回摘要。
+- children 过滤应紧跟 meta 读取执行，早于运行态、等待状态计算，以减少无关会话开销。
+- stdio MCP 与 Codex App 兼容工具的现有描述文字不同；两者都需明确“默认全部、children 为当前来源直接 MCP 子对话”，并添加同一 enum schema。
+- 两处 schema 均设置 `additionalProperties: false`，新增 `scope` 后不会影响既有 agent/status/limit 参数。
+- 回归中可在首个 `mcpCreate` 完成并验证 `createdFrom` 后调用列表：此时当前来源只有一个直接 MCP 子会话，适合断言精确集合。
+- 省略 scope 与显式 all 的兼容性可比较同参数调用返回的会话 ID 数组；children 应包含新建子会话且排除来源会话。
+- README 当前仅有一行轻量元数据描述，可直接补充 `scope=children` 的行为与默认 all。
+- 现有回归没有 branch 会话夹具；为验证 `kind === 'mcp'` 条件，需要在回归中创建一个来自同一来源的 branch，或构造等价持久会话夹具。
+- 项目只有 `npm run regression` 这一完整回归入口；失败测试与最终验证均需用 `timeout 60s` 包裹。
+- `handleNewSession` 创建 branch 后会把测试 WebSocket 切换到新会话；为避免干扰后续事件断言，children scope 回归应直接在临时 sessions 目录写入最小 branch/孙级夹具。
+- `buildSessionInfoPayload` 虽会返回 `createdFromKind`，但 children MCP 过滤不应依赖当前 WebSocket 查看状态。
+- 会话元数据完整解析阈值默认 512 KiB、preview 头尾各 128 KiB；已有 `session-preview-metadata` 定向回归以更小阈值强制走 preview 分支。
+- 该定向回归已覆盖 preview 中的 `createdFrom.kind`，可扩展来源 ID 或通过内部 MCP 验证 children 过滤，避免只测试小文件路径。
+- `runSessionPreviewMetadataRegression` 已配置独立内部 MCP token，可将 tail 夹具改为 `kind: mcp + sourceSessionId`，随后调用 `ccweb_list_conversations(scope=children)` 精确断言；这是最小且快速的失败回归入口。
+- preview 定向回归无需真实父会话文件：列表过滤只使用自动传入的来源 ID 与子会话持久元数据比对。
+- 主回归已直接导入 `lib/ccweb-mcp-server.js` 的 `TOOLS`，可对 stdio/shared MCP 的 scope enum 与描述做结构化断言。
+- Codex App 当前主路径走线程级 MCP；`codexAppCommunicationDynamicTools` 是兼容定义，仍需同步文字与 schema，可用已有 server 源码审计断言或行为回归覆盖。
+- 回归已有 `assertCcwebDisplayImageContract` 这类静态契约函数和 target 分派模式；可新增列表 scope 契约函数，并在 `session-preview-metadata` 定向目标及完整回归中复用。
+- 完整回归后续没有对全局会话数量做精确断言，仅按 ID 查找；增加 branch 与孙级临时会话夹具不会破坏后续场景。
+- 新增测试语法检查通过；实现前定向回归稳定失败在 stdio/shared MCP 缺少 scope enum，证明失败测试有效。
+- 实现后 `server.js`、`lib/ccweb-mcp-server.js`、`scripts/regression.js` 语法检查全部通过，preview 定向回归通过。
+- 服务端将任何非 `children` 值归一为 `all`；children 在运行态/等待态计算、排序和 limit 前完成过滤。
+- 最终语法检查、session-preview-metadata 定向回归、完整 `npm run regression` 与 `git diff --check` 全部通过。
+- 最终局部差异确认核心改动仅落在会话元数据、列表过滤、两处 MCP 契约、README 与回归断言；工作树中的任务看板等大段 diff 为既有改动，未被覆盖。
+- 差异审查发现 preview 测试不应把原有 `ccweb_prompt_user` 夹具改写为 `mcp`；将改为新增独立大文件 MCP 子会话夹具，以保留旧覆盖。
+- 已完成上述修正，定向回归、完整回归和 diff check 再次通过；没有剩余代码风险或阻塞。
+- 无需重启服务即可完成代码交付；本轮未执行服务重启。
+- 最终文件行号已核验，临时 CSV 已不存在，`git diff --check` 仍通过。
+- 重启前运行态检查发现除当前对话外还有 2 个 running 对话；按项目运维规则暂缓 `pm2 restart ccweb --update-env`。
+
+## 技术决策
+
+| 决策 | 理由 |
+|------|------|
+| 支持 `scope: "all" | "children"` | schema 显式、可验证；默认 all 向后兼容 |
+| children 匹配 `createdFrom.kind === "mcp" && createdFrom.sourceSessionId === sourceSessionId` | 精确表达直接持久子对话，不混入分支对话 |
+| 非法 scope 回退 all | 正常 MCP 由 enum 约束，服务内部调用仍保持兼容与可预测 |
+| 不依赖 LLM 上下文或 pending reply 状态 | 子会话持久元数据才是可重启恢复的权威来源 |
+| 暂不新增返回字段 | 用户只要求过滤能力，遵循 YAGNI；现有摘要字段足以继续投递消息 |
+
+## 风险
+
+- 大会话文件可能走 preview 解析路径，需要确保 preview 元数据能读取 `createdFrom.sourceSessionId`。
+- limit 必须在 children 过滤后应用。
+- 回归测试已有大量并行任务新增内容，插入断言时避免更改无关逻辑。
+- 需分别断言省略 scope、scope=all、scope=children 和非法 scope。
+- 本轮 `codebase-memory-mcp` transport 已关闭；按降级策略使用本地检索，不再重复失败调用。
+
+## 资源
+
+- `server.js`：列表实现、会话元数据解析、Codex App 工具 schema。
+- `lib/ccweb-mcp-server.js`：stdio MCP 工具 schema 与提示词。
+- `scripts/regression.js`：MCP 创建及列表回归。
+- `README.md`：MCP 能力说明。

.planning/2026-08-11-ccweb-list-children-scope/progress.md

@@ -0,0 +1,116 @@
+# 进度日志：ccweb_list_conversations children scope
+
+## 会话：2026-08-11
+
+### 阶段 1：核对现状与重叠改动
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 22:56 +08:00
+- 已完成动作：
+  - 读取 `planning-with-files` 与 `todo-list-csv` 技能说明。
+  - 运行 session catchup，未发现需恢复的未同步上下文。
+  - 检查 Git 工作树，确认三个目标文件存在其他任务未提交改动。
+  - 建立本任务独立规划目录和六步计划。
+  - 独立计划审查通过；采纳兼容性、非法参数、直接子会话判定和定向验证建议。
+  - 使用本地检索确认目标代码行及回归入口；相关区域没有既有未提交 diff，仍按当前文件内容局部修改。
+  - 核对大小会话元数据解析路径，确认可从现有 `createdFrom` preview 直接提取来源 ID。
+
+### 阶段 2：编写失败回归断言
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 23:10 +08:00
+- 计划动作：
+  - 扩展 session preview 定向回归，先证明 scope 尚未生效。
+  - 扩展主回归覆盖兼容 all、直接 children、branch/孙级排除与非法 scope。
+- 完成动作：
+  - 新增 stdio/shared MCP 与 Codex App 兼容工具提示词/schema 契约断言。
+  - 新增大文件 preview children 过滤定向断言。
+  - 新增小文件默认/all/非法 scope、branch 与孙级排除断言。
+
+### 阶段 3：实现列表过滤与 MCP 契约
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 23:13 +08:00
+- 计划动作：
+  - 扩展会话元数据来源 ID。
+  - 在排序和 limit 前执行 children 过滤。
+  - 同步两处工具描述与 schema。
+- 完成动作：
+  - 完整解析和 preview 元数据均提取 `createdFromSourceSessionId`。
+  - `scope=children` 只匹配当前来源的直接 MCP 子会话。
+  - stdio/shared MCP 与 Codex App 兼容 schema 均暴露 `all/children`，提示词同步说明语义。
+
+### 阶段 4：更新 README 与规划记录
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 23:16 +08:00
+- 计划动作：
+  - 更新 MCP 表格和设计边界说明。
+  - 核对规划记录与实现一致。
+- 完成动作：
+  - README 表格记录默认 `scope=all` 和 `scope=children`。
+  - README 设计边界明确排除 branch 与更深层后代。
+
+### 阶段 5：运行定向及完整回归验证
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 23:17 +08:00
+- 计划动作：
+  - 重跑定向回归、语法检查和 diff check。
+  - 在 60 秒上限内运行完整回归。
+- 完成动作：
+  - 三个 JavaScript 文件语法检查通过。
+  - session preview 定向回归通过。
+  - 完整回归在硬超时内通过，输出 `Regression checks passed.`。
+  - `git diff --check` 通过。
+
+### 阶段 6：差异审查与交付
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 23:19 +08:00
+- 计划动作：
+  - 审查目标文件最终差异与行号。
+  - 确认未覆盖其他任务改动。
+  - 完成 CSV 状态并清理临时清单。
+- 审查发现：需要保留 preview 回归原有 `ccweb_prompt_user` kind 覆盖，另增 MCP child 夹具；修正后重跑验证。
+- 完成动作：
+  - 保留原有 preview kind 夹具，新增独立的大文件 MCP 子会话夹具。
+  - 修正后语法、定向回归、完整回归和 diff check 再次全部通过。
+  - 审查局部 diff，确认未覆盖其他对话的未提交改动。
+  - 将临时 CSV 全部推进为 DONE，准备按技能规则清理。
+  - TODO CSV 状态工具确认 `6/6 DONE` 后已删除；最终存在性检查与 diff check 通过。
+  - 检查运行会话：另有 2 个对话处于 running，按规则未重启 cc-web，避免中断其他任务。
+- 创建/修改文件：
+  - `.planning/2026-08-11-ccweb-list-children-scope/task_plan.md`
+  - `.planning/2026-08-11-ccweb-list-children-scope/findings.md`
+  - `.planning/2026-08-11-ccweb-list-children-scope/progress.md`
+  - `ccweb会话子范围 TO DO list.csv`
+
+## 测试结果
+
+| 测试 | 输入 | 预期 | 实际 | 状态 |
+|------|------|------|------|------|
+| 回归脚本语法 | `node --check scripts/regression.js` | 通过 | 通过 | ✓ |
+| children scope 失败回归 | `node scripts/regression.js --target session-preview-metadata` | 实现前失败 | 缺少 scope enum，退出 1 | ✓ |
+| 三文件语法检查 | `node --check` | 全部通过 | 全部通过 | ✓ |
+| children scope 定向回归 | `node scripts/regression.js --target session-preview-metadata` | 通过 | 通过 | ✓ |
+| 完整回归 | `npm run regression` | 60 秒内通过 | `Regression checks passed.` | ✓ |
+| 差异空白检查 | `git diff --check` | 通过 | 通过 | ✓ |
+| 修正后完整回归 | `npm run regression` | 60 秒内通过 | `Regression checks passed.` | ✓ |
+
+## 错误日志
+
+| 时间 | 错误 | 尝试 | 解决方式 |
+|------|------|------|----------|
+| 2026-08-11 22:56 +08:00 | 项目内 todo-list-csv 技能路径不存在 | 1 | 改用会话公布的 `/home/hdzx/.codex/skills/todo-list-csv/` |
+| 2026-08-11 23:00 +08:00 | codebase-memory-mcp `Transport closed` | 3 | 停止重试，降级到本地 `rg/sed/git diff` |
+
+## 五问恢复检查
+
+| 问题 | 回答 |
+|------|------|
+| 当前在哪？ | 阶段 1，核对实现与重叠改动 |
+| 接下来去哪？ | 失败回归、实现、文档、验证、交付 |
+| 目标是什么？ | 增加兼容的 children scope 并更新提示词 |
+| 学到了什么？ | 见 findings.md |
+| 做了什么？ | 见上方阶段日志 |

.planning/2026-08-11-ccweb-list-children-scope/task_plan.md

@@ -0,0 +1,80 @@
+# 任务计划：ccweb_list_conversations children scope
+
+## 目标
+
+为 `ccweb_list_conversations` 增加兼容默认行为的 `scope: "all" | "children"`，让来源对话能查询自己通过 MCP 创建的持久子对话，并同步提示词、schema、回归测试和文档。
+
+## 当前阶段
+
+已完成
+
+## 阶段
+
+### 阶段 1：核对现有接口、提示词、回归覆盖与工作树重叠
+
+- [x] 核对服务端列表实现、两处工具 schema、README 和回归入口
+- [x] 审查工作树中与本任务重叠的既有改动并保留其语义
+- **状态：** complete
+
+### 阶段 2：为 children scope 编写失败回归断言
+
+- [x] 新增省略 `scope` 与显式 `all` 返回完全一致的兼容断言
+- [x] 新增 `children` 只匹配 `kind === 'mcp'` 且来源 ID 为当前调用上下文的直接子会话断言
+- [x] 新增非法 `scope` 保守回退 `all` 的服务端断言
+- [x] 先运行定向回归，确认新断言在实现前失败
+- **状态：** complete
+
+### 阶段 3：实现列表过滤与双端 MCP schema/描述
+
+- [x] 按 `createdFrom.kind === 'mcp'` 与来源会话 ID 过滤
+- [x] 更新 stdio MCP 与 Codex App 工具描述、参数 schema
+- **状态：** complete
+
+### 阶段 4：更新 README 文档与规划记录
+
+- [x] 记录 `scope` 默认值、children 语义和适用边界
+- [x] 同步发现、决策与进度
+- **状态：** complete
+
+### 阶段 5：运行定向及完整回归验证
+
+- [x] 运行语法检查，并定向覆盖列表实现、stdio MCP schema 与 Codex App 工具描述
+- [x] 在 60 秒超时约束下运行完整回归
+- **状态：** complete
+
+### 阶段 6：审查差异、清理临时清单并完成交付
+
+- [x] 检查差异只追加本任务语义且未覆盖用户改动
+- [x] 将 CSV 全部推进为 DONE 后清理
+- [x] 保留 `.planning/2026-08-11-ccweb-list-children-scope/` 作为长期任务记录
+- **状态：** complete
+
+## 关键问题
+
+1. `children` 是否仅包含 `createdFrom.kind === 'mcp'` 的直接子对话？
+2. 默认省略 `scope` 时是否完全保持当前全量列表行为？
+3. 过滤应在 limit 之前还是之后执行？
+4. 返回结构是否需要新增父子字段，还是只改变列表集合？
+
+## 决策
+
+| 决策 | 理由 |
+|------|------|
+| `scope` 默认 `all` | 保持现有调用完全兼容 |
+| `children` 仅返回当前来源直接通过 MCP 创建的会话 | 与用户提出的“我曾创建的子对话”语义一致，排除 branch 与孙级会话 |
+| 非法 `scope` 在服务实现中回退 `all` | schema enum 会拦截正常 MCP 调用；内部兼容入口保持保守且不破坏旧行为 |
+| 先过滤、再排序、再应用 limit | 避免全局热门会话占满 limit 后漏掉子对话 |
+| 不在父会话维护 children 数组 | 现有子会话 `createdFrom` 已是权威数据，避免双写一致性问题 |
+
+## 遇到的错误
+
+| 错误 | 尝试 | 解决方式 |
+|------|------|----------|
+| 项目内 `/home/cc-web/.codex/skills/todo-list-csv/SKILL.md` 不存在 | 1 | 使用会话公布的有效路径 `/home/hdzx/.codex/skills/todo-list-csv/SKILL.md` |
+| `codebase-memory-mcp` 连续返回 `Transport closed` | 3 | 停止重复调用，基于此前已确认入口降级为本地 `rg/sed/git diff` |
+
+## 约束
+
+- 保留工作树中其他对话已存在的 `server.js`、`lib/ccweb-mcp-server.js`、`scripts/regression.js` 改动。
+- 测试命令最大超时 60 秒。
+- 不重启服务；若后续确有必要，先按项目规则检查其他运行中对话。

.planning/2026-08-11-failed-insert-card-actions/findings.md

@@ -0,0 +1,103 @@
+# 失败插入卡片重试与删除：发现记录
+
+## 用户需求
+
+- 用户希望“插入失败”的卡片增加“重试”和“删除”按钮。
+- 截图中的失败项位于用户消息卡片内，包含图片预览、文件名、尺寸/状态信息和红色“插入失败”状态。
+
+## 视觉观察
+
+- 当前失败状态只有红点和“插入失败”文本，没有恢复或清理入口。
+- 操作应靠近失败状态区域，保持卡片宽度和当前主题视觉，不应抢占消息正文。
+
+## 工作区约束
+
+- 当前分支为 `main`，已有另一任务留下的未提交改动。
+- 已确认 `.trellis/.current-task` 指向 `08-11-task-board`，本任务不会覆盖该指针。
+- 与本任务可能重叠的已修改文件包括 `public/app.js`、`public/index.html`、`scripts/regression.js` 和 `server.js`；后续必须做局部差异审查。
+
+## 待确认的代码事实
+
+- 失败状态的数据结构、稳定标识和持久化位置。
+- 原始插入请求的入口、请求参数及重试时可复用的数据。
+- 删除应落在草稿状态、消息附件状态还是服务端持久化层。
+- 现有测试中与运行时图片插入相关的覆盖位置。
+
+## 初步代码定位
+
+- `codebase-memory-mcp` 项目 `home-cc-web` 索引状态为 `ready`（5737 节点、12312 边）。
+- “插入失败”不是普通上传失败文案，而是 Codex App 运行中消息插入（steer）状态：前端入口命中 `codexAppSteerStatusLabel` 与相邻的 `setCodexAppSteerStatusElement`。
+- 服务端入口命中 `handleCodexAppSteerMessage`：`turn/steer` 成功发送 `inserted`，失败发送 `failed`，且消息会先以 `persistedUserMessage` 写入会话。
+- 下一步需要确认状态事件携带的稳定标识、前端如何找到对应用户消息，以及重试是否可以复用现有 `handleCodexAppSteerMessage` 消息形状。
+
+## 已确认的数据与渲染契约
+
+- 前端 `updateCodexAppSteerMessage(clientMessageId, status, message)` 使用 `userMessageIndex` 或消息元素的 `data-message-id` 精确定位卡片，稳定标识已经存在，无需按文件名匹配。
+- `setCodexAppSteerStatusElement` 目前只切换 `pending / inserted / failed` 三种 CSS class，并把状态区域写成纯文本；操作按钮应由这里或紧邻的单一渲染函数统一维护，避免重复绑定。
+- 服务端回归 `runCodexAppRuntimeImageSteerRegression` 已覆盖 `clientMessageId`、失败状态和成功插入；失败的“附件不可用”消息明确不会持久化，说明截图里的失败卡片至少有一类是客户端临时项。
+- 现有成功分支会持久化一条带附件的用户消息，并最终发送 `inserted`；重试实现必须避免把失败项或成功项重复写入会话。
+
+## 调用链与主要风险
+
+- `handleServerMessage` 仅在 `codex_app_steer_status` 分支调用 `updateCodexAppSteerMessage`；当前状态事件已是最小可扩展协议面。
+- `handleCodexAppSteerMessage` 在真正调用 `turn/steer` **之前** 把用户消息写入会话。若 `turn/steer` 异步失败，该持久化消息当前不会回滚，因此“重试”若直接重发原消息会造成重复持久化。
+- 失败分为两类：附件解析/空消息等同步前置失败（未持久化）与准备/`turn/steer` 异步失败（可能已持久化）。删除和重试必须能区分或统一修正这两类，否则刷新后的行为会不一致。
+- 下一步要确认本地消息对象是否保存 `clientMessageId`、服务端是否已有单条消息删除/替换协议，以及附件引用在失败后是否仍可用。
+
+## 客户端入口补充
+
+- `sendMessage` 为运行中 Codex App 插入创建本地 `messageId`，用该值注册 `userMessageIndex`，并作为 WebSocket 消息的 `clientMessageId` 发送；因此失败卡片已有天然的单项操作键。
+- 当前前后端没有通用的“删除单条消息”协议；仅有排队消息、提示卡等其他局部删除实现，不能直接用于持久化的 steer 用户消息。
+- 需要在服务端把 `clientMessageId` 与持久化消息关联起来，或在 steer 失败时回滚该消息，才能让删除和重试同时满足“不重复”和“刷新一致”。
+
+## 可行实现方向
+
+- 本地卡片由 `sendMessage` 创建，包含完整 `text` 与克隆后的 `attachments`；扩展 `userMessageIndex` 即可保存重试载荷，不需要从 DOM 反解析。
+- `createMsgElement` 是失败状态和附件预览的共同装配点，`setCodexAppSteerStatusElement` 是状态区域的唯一更新点，适合统一创建/移除按钮并维护 `disabled` / `aria-busy`。
+- 推荐服务端在真实 `turn/steer` 最终失败时按对象引用回滚刚持久化的用户消息。这样所有失败卡片都保持客户端临时态，删除无需新增持久化删除协议，重试也不会制造历史重复项。
+- 重试仍需校验当前 Codex App turn 是否在运行；若运行已结束，应给出明确失败状态，不能让卡片永久停在 `pending`。
+
+## 本地源码校验
+
+- 当前样式集中在 `public/style.css` 的 `.codex-steer-*` 区域，失败卡片已有红色边框/背景和 11px 状态行；新操作可在同一区域追加，避免影响其他消息卡片。
+- 项目没有 DOM 测试依赖，仅有 `node scripts/regression.js`；前端交互测试需要使用轻量假 DOM/纯函数抽取，或在现有回归中增加协议和静态契约断言。
+- 本任务开始时的重叠文件基线：`public/app.js` 已有 +155 行、`server.js` +532/-7 行、`scripts/regression.js` +73/-11 行、`public/index.html` +14 行，均来自既有“任务看板”工作，后续差异必须按目标函数/样式区段核对。
+- `public/style.css` 当前没有未提交改动，是本任务新增样式的低冲突落点。
+
+## 测试与冲突边界
+
+- 现有 `runCodexAppStaleRunningRegression` 已有一个稳定的 `expectedTurnId` 不匹配失败夹具，适合新增“失败后持久化消息已回滚”的服务端断言。
+- 现有成功恢复分支已断言用户消息只持久化一次，可继续保护“重试/恢复不重复”。
+- 既有未提交 diff 的 hunk 不覆盖 `setCodexAppSteerStatusElement`、`sendMessage` 或 `handleCodexAppSteerMessage` 主体；可以对这些区段做局部补丁，但最终仍需逐 hunk 复核。
+- 仓库已有未跟踪的任务看板 MiniDOM 单测脚本，但它属于另一任务；本功能不能修改或依赖该未提交测试文件。若需要 DOM 单测，应建立独立、最小的测试入口。
+
+## 失败夹具与规范结论
+
+- mock app-server 的 mismatch 夹具会保留一个不同的活动 turn，因此每次 `turn/steer` 都稳定返回 `expectedTurnId does not match active turn`；可用于重复验证失败与回滚，但不能作为成功重试夹具。
+- 前端 Trellis 规范除“静态资源版本握手”外大部分仍是模板占位，没有额外组件框架约束；本任务应遵循仓库现有原生 DOM + CSS 组织方式。
+- 回归脚本已有按 target 执行的分支，可为本功能提供小范围测试入口，避免每次执行完整回归超过 60 秒。
+
+## 资源
+
+- 用户截图：`sessions/_attachments/8da11ed4-5989-4d30-a12a-f27522138799.png`
+- Trellis 任务：`.trellis/tasks/08-11-failed-insert-card-actions/`
+
+## 最终实现状态
+
+- 前端新增 `codexAppSteerRecords`，保存失败项的原文本、附件、会话、模式和 agent；重试沿用同一 `clientMessageId`，并通过 `status + inFlight` 阻止重复发送。
+- failed 状态统一渲染“重试”“删除”；pending/inserted 移除操作，卡片使用 `aria-busy`，状态行使用 `role=status` 与 `aria-live=polite`。
+- 本地运行中插入不再提前增加 `currentSessionMessageCount`，只有收到 `inserted` 才提交消息索引；失败/删除不会制造普通路径的索引漂移。
+- 服务端为临时 steer 用户消息写入稳定 `id`，真正的 `turn/steer` 最终失败时先按 id 从最新会话回滚，再发 failed 状态；stale recovery 成功路径保持一次持久化。
+- 前端 MiniDOM 单测覆盖失败操作、双击保护、载荷复用、再次失败恢复、删除单项、断线/跨会话/turn 结束保护与成功索引提交。
+
+## 验证结果
+
+- `node scripts/failed-insert-card-unit.js`：通过。
+- `node scripts/regression.js --target runtime-image-send`：通过。
+- `node --check public/app.js`、`server.js`、`scripts/regression.js`：通过。
+- `node scripts/regression.js`：因首次定向命令参数错误而实际执行，完整回归通过（约 46 秒）。
+
+## 独立审查修正
+
+- 检查代理发现 `options.emitUserMessage` 的程序化 `session_message` 虽会显示失败操作，但缺少原始重试载荷；现已由服务端附加临时 steer 元数据，前端据此建立同样的重试记录。
+- 主线程进一步将这类 `session_message` 在结果未定时保持为临时项：不提前写入消息缓存、不提前占用 `currentSessionMessageCount`，收到 `inserted` 后才提交，避免失败删除后的缓存幽灵和索引漂移。

.planning/2026-08-11-failed-insert-card-actions/progress.md

@@ -0,0 +1,63 @@
+# 失败插入卡片重试与删除：进度日志
+
+## 2026-08-11
+
+### 初始化与定位
+
+- **状态：** `complete`
+- 已扫描可用技能并完整读取 `planning-with-files`、`todo-list-csv` 主说明。
+- 已运行 planning session catchup，未发现需要恢复的未同步上下文。
+- 已读取 Trellis 会话上下文，确认开发者为 `shiyue`，现有活动任务为“独立任务看板”。
+- 已创建独立 Trellis 任务 `08-11-failed-insert-card-actions`，但未切换全局当前任务指针。
+- 已记录截图中的失败卡片结构和现有工作区重叠风险。
+- 独立计划审查已通过；已吸收稳定标识、忙碌状态和定向测试优先等建议。
+- 已创建 Trellis PRD，并为实施/检查配置前端规范上下文。
+- 已确认 codebase-memory 索引可用，并初步定位到 Codex App `turn/steer` 的前后端状态链路。
+- 已完成调用链、失败持久化、临时消息索引和测试夹具分析，并写入 Trellis 研究文档。
+
+### 交互契约与回归测试
+
+- **状态：** `complete`
+- 已明确失败项使用 `clientMessageId` 定位、失败持久化回滚、临时消息延迟提交索引、重试并发保护和客户端删除语义。
+- 下一步先补回归测试，再写最小实现。
+
+### 实现、样式与定向验证
+
+- **状态：** `complete`
+- 已实现失败卡片的重试、删除、防重复点击、可访问状态和消息索引延迟提交。
+- 已实现服务端最终 steer 失败的精确持久化回滚及错误关联 id。
+- 已新增独立 MiniDOM 前端单测并扩展 runtime image mismatch 回滚断言。
+
+### 差异审查与完整回归
+
+- **状态：** `complete`
+- 已完成主线程首轮目标函数审查；下一步由独立检查代理按 PRD、研究契约和现有脏工作区边界复核。
+- 独立检查已修复程序化 `session_message` 缺少重试载荷的问题；主线程补齐其临时缓存/索引语义，并扩展成功提交断言。
+- 修正后前端单测、`runtime-image-send` 定向集成和 `node --check public/app.js` 再次通过。
+- `git diff --check` 通过；目标修改保持在既定函数、CSS 区段和测试范围，未回退任务看板或消息回传的并行改动。
+
+### 清理与交付
+
+- **状态：** `complete`
+- 已检查运行对话：除当前对话外仍有“设计任务看板状态机制”和“统一 ccweb 消息回传接口”处于 `running`，按运维规则暂不重启 `ccweb`。
+- 规范沉淀判断：本次结论属于 Codex App steer 的任务级协议细节，已完整记录在 Trellis 研究文档；没有形成需要写入通用前端规范的新约定，因此不修改 `.trellis/spec/`。
+- 已将 Trellis 任务元数据标记为完成，并按 `todo-list-csv` 工作流删除本任务临时 CSV；持久化计划与研究文档保留用于审计。
+
+## 测试结果
+
+| 测试 | 预期 | 实际 | 状态 |
+|---|---|---|---|
+| 前端失败卡片单测 | 重试/删除/并发/无障碍/边界保护通过 | 全部通过 | ✓ |
+| Runtime image send 定向集成 | 成功、stale recovery、mismatch 回滚通过 | 全部通过 | ✓ |
+| 完整回归 | 项目全部回归通过 | 全部通过（误执行但有效） | ✓ |
+| JavaScript 语法检查 | 三个目标脚本语法有效 | 全部通过 | ✓ |
+
+## 错误日志
+
+| 时间 | 错误 | 尝试 | 处理 |
+|---|---|---:|---|
+| 2026-08-11 23:00 +08:00 | 新建 Trellis 任务后读取到缺失的 `prd.md` | 1 | 该脚本只生成任务元数据与上下文模板，已按提示显式创建 PRD |
+| 2026-08-11 23:20 +08:00 | `codebase-memory-mcp` transport closed | 1 | 已保留先前 MCP 命中结果，剩余小范围源码用本地检索降级校验 |
+| 2026-08-11 23:30 +08:00 | 前端单测跨 realm 深比较失败 | 1 | 将沙箱载荷规范化为普通 JSON 对象后再断言，并清理重复的 `inFlight` 赋值 |
+| 2026-08-11 23:35 +08:00 | 定向回归漏写 `--target` | 1 | 命令实际跑成完整回归且通过；已确认正确 CLI，避免再次执行完整套件 |
+| 2026-08-11 23:38 +08:00 | 计划同步补丁使用了不存在的标题锚点 | 1 | 补丁未生效；读取实际文件后以现有区段重新应用 |

.planning/2026-08-11-failed-insert-card-actions/task_plan.md

@@ -0,0 +1,55 @@
+# 失败插入卡片重试与删除：任务计划
+
+## 目标
+
+为图片/附件“插入失败”卡片增加可用的“重试”和“删除”操作：重试沿用原附件并正确更新卡片状态，删除只移除对应失败项；同时保证重复点击、再次失败、会话恢复和现有发送流程不被破坏。
+
+## 范围
+
+- 失败卡片的前端渲染、事件处理和状态同步。
+- 必要的后端/API 复用或补充。
+- 定向回归测试、样式和无障碍状态。
+- 不重构无关消息链路，不覆盖当前工作区中的“独立任务看板”改动。
+
+## 阶段
+
+1. **初始化任务上下文并定位失败附件链路** — `complete`
+2. **明确重试与删除交互契约并补充回归测试** — `complete`
+3. **实现失败卡片重试与删除行为** — `complete`
+4. **完善操作按钮样式与无障碍状态** — `complete`
+5. **运行定向测试并修复问题** — `complete`
+6. **执行差异审查与完整回归** — `complete`
+7. **清理临时跟踪文件并交付** — `complete`
+
+## 验收条件
+
+- 仅失败卡片展示“重试”和“删除”。
+- 点击“重试”后复用原附件，进入明确的处理中状态；成功后不再显示失败操作，失败后恢复可重试状态并保留可理解的错误提示。
+- 重试过程中禁用重复操作，避免并发插入或重复提交。
+- 点击“删除”只移除目标失败卡片，不影响消息文本、其他附件或其他消息。
+- 刷新/恢复会话后的失败卡片仍可执行两项操作，或按现有持久化边界保持一致行为。
+- 定向测试与项目相关回归通过；无新增控制台错误。
+
+## 关键决策
+
+| 决策 | 原因 |
+|---|---|
+| 使用独立 `.planning` 与 Trellis 任务目录，不切换 `.trellis/.current-task` | 当前工作区另有“独立任务看板”任务正在运行，避免跨会话状态覆盖 |
+| 先追踪现有插入请求和失败状态，再决定是否新增 API | 优先复用既有链路，减少协议与持久化风险 |
+| 以失败项标识作为重试/删除目标，不按文件名匹配 | 同名附件可能同时存在，必须精确操作单项 |
+
+## 风险与约束
+
+- `public/app.js`、`server.js` 等文件已有未提交改动；补丁必须保持局部并在最终差异中区分本任务内容。
+- 删除属于界面内失败项清理，不删除用户磁盘上的原始文件或服务器无关资源。
+- 所有自动化测试单次运行控制在 60 秒内。
+
+## 错误记录
+
+| 错误 | 尝试 | 处理 |
+|---|---:|---|
+| Trellis 新任务默认未生成 `prd.md` | 1 | 按工作流要求显式创建 PRD，并保留已生成的上下文清单与任务元数据 |
+| `codebase-memory-mcp` 补查 `send` / `clearUserMessageIndex` 时 transport closed | 1 | 核心链路已通过 MCP 确认；剩余局部实现按约定降级为 `rg/sed` 校验，不重复相同失败调用 |
+| 前端单测跨 `vm` 上下文对象被 `deepStrictEqual` 判为原型不一致 | 1 | 对实际发送载荷先做 JSON 规范化，再比较纯数据结构；功能载荷本身完全一致 |
+| 回归命令漏写 `--target`，误执行完整回归 | 1 | 完整回归已通过；查明 CLI 只解析 `--target` 或环境变量，后续仅补跑未覆盖的专项目标 |
+| 计划同步补丁引用了研究文档中的错误标题 | 1 | 补丁未生效；读取实际计划文件后改用现有“资源”区段作为追加锚点 |

.planning/2026-08-11-help/findings.md

@@ -0,0 +1,42 @@
+# Findings & Decisions
+
+## Requirements
+- 新增独立任务看板，不影响现有聊天、会话列表、MCP 和 Codex App 行为。
+- 普通对话默认不进入任务池；提供“加入任务看板”开关。
+- 支持系统固定状态与用户自定义状态。
+- Agent 可通过 MCP 主动上报；未上报时由 cc-web 生命周期 Hook 自动分类。
+- 归档由用户或服务端策略触发，不允许 Agent 隐式归档。
+- 三个实现对话完成后，必须由第四个集成对话统一接线和测试。
+- 集成测试通过且无其他 running 对话后才允许重启 cc-web。
+
+## Research Findings
+- 当前会话列表只有运行态 isRunning，没有任务状态或归档字段。
+- cc-web 已能观察 turn started/completed、工具调用、用户输入等待和失败事件，可实现自身 Hook。
+- Codex Goal 只适用于 Codex App，不能作为跨 Agent 看板的唯一状态源。
+- 多个对话共享同一工作区，中心文件必须避免并发修改。
+- 项目必需命令是 `node --check` 与 `npm run regression`；不存在通用 lint/typecheck 脚本。
+- Trellis 任务已创建为 `.trellis/tasks/08-11-task-board` 并设为 current。
+- 共享数据、WebSocket、MCP、Hook 与文件所有权契约已写入该任务的 `info.md`。
+- 当前来源对话 ID 为 `56bb82c6-4fa3-4cb8-bb84-6969e6547d3a`，重启门禁只能排除该 ID。
+
+## Technical Decisions
+| Decision | Rationale |
+|----------|-----------|
+| 系统状态使用稳定 ID，自定义状态映射到 baseStatus | 标签可编辑，同时保留自动化语义 |
+| taskTracking.enabled 控制是否进入任务池 | 关闭时不分类、不展示，也不等于归档 |
+| MCP、Hook、UI 共用一个任务状态服务 | 防止三套状态逻辑漂移 |
+| Hook 作为 MCP 缺失时的兜底，用户操作优先级最高 | 保证可控并降低误判影响 |
+| MCP 对话负责共享 TaskBoardService，Hook 对话只实现事件归约器 | 确保并行可实现且第四个对话可机械集成 |
+
+## Issues Encountered
+| Issue | Resolution |
+|-------|------------|
+| 规划初始化目录名称不理想 | 继续复用，不影响功能代码与最终集成 |
+| 首次计划审查未通过 | 按四项阻断意见补齐契约、Trellis、测试和重启门禁后复审 |
+
+## Resources
+- 参考图：sessions/_attachments/42432a7d-778d-4dca-8156-d5bd651d242d.png
+- 项目约束：AGENTS.md、.trellis/workflow.md
+- 前端实现对话：b94ec6fe-5438-48a3-9733-4028bfd9198f
+- MCP 实现对话：972a6903-4860-4558-9ab0-4e124bffa363
+- Hook 实现对话：27651660-a64d-4b01-8606-500468e9c599

.planning/2026-08-11-help/progress.md

@@ -0,0 +1,61 @@
+# Progress Log
+
+## Session: 2026-08-11
+
+### Current Status
+- **Phase:** 4 - 集成返工：删除伪优先级并合并控制栏
+- **Started:** 2026-08-11
+
+### Actions Taken
+- 已确认采用四个 cc-web 对话：前端、MCP、Hook、最终集成。
+- 已读取 planning-with-files、todo-list-csv、frontend-skill。
+- 已确定并行实现阶段不修改共享中心文件。
+- 已创建并启动 Trellis 任务 `08-11-task-board`。
+- 已写入 PRD、技术设计和并行集成契约。
+- 首次计划审查发现 4 个阻断问题，均已修正，等待复审。
+- 已通过 `ccweb_list_conversations` 记录当前来源对话 ID：`56bb82c6-4fa3-4cb8-bb84-6969e6547d3a`。
+- 计划第三次复审已通过，无阻断问题。
+- 已并行创建前端对话 `b94ec6fe-5438-48a3-9733-4028bfd9198f`，reply request `6f4c2836-f473-4cfe-97fa-fd3f58d356c4`。
+- 已并行创建 MCP 对话 `972a6903-4860-4558-9ab0-4e124bffa363`，reply request `c4c3b580-0678-4152-995c-9f6dcf7eebad`。
+- 已并行创建 Hook 对话 `27651660-a64d-4b01-8606-500468e9c599`，reply request `0997a46b-fe03-42cf-af1f-235a61aa5851`。
+- 三个 reply 均处于 waiting；首次 30 秒轮询尚无完成项。
+- `config/cross-conversation-replies.json` 因 requestReply 运行态自动更新，视为 cc-web 运行态记录，不由本任务手工修改。
+- 第二次轮询三路仍为 running；中心文件与功能白名单文件尚未出现写入，暂无冲突。
+- 第三次轮询三路仍为 running，子会话尚未持久化 assistant 终态消息，继续等待而不打断。
+- 三个 `codexapp-state.json` 持续刷新，说明 turn 仍有活动；会话 JSON 仍只含初始用户消息，尚未到终态持久化阶段。
+- 中断恢复后再次检查：三路 `turnStatus` 均为 `running`、`error=null`，没有等待用户输入；前端分支已开始落盘 `public/task-board.js`，其余分支仍在实现中。
+- 14:09 检查：前端与 Hook 已分别落盘 `public/task-board.js`、`lib/task-board-lifecycle.js`，仍在继续补齐模块和测试；MCP 分支仍运行且无错误，尚未返回终态。
+- 前端首轮在仅落盘 `public/task-board.js` 时异常提前结束：缺少 CSS、单测和最终说明，未计为通过。已向同一前端对话发送续做消息并成功恢复运行，没有新建替代对话。
+- 前端续做已补齐 `public/task-board.css`，正在编写契约单测；Hook 的模块与单测均已落盘并在自检；MCP 分支进入原子保存、回滚和状态错误码设计，三路仍无运行错误。
+- 一次 `ccweb_list_pending_replies` 监控调用在 60 秒后超时，已降级为读取本地会话运行态；实现本身无错误。前端三文件与 MCP 的 service/mcp 两文件均已落盘，MCP 单测尚待补齐。
+- MCP 分支已返回，且严格只新增 `lib/task-board-service.js`、`lib/task-board-mcp.js`、`scripts/task-board-service-unit.js`。主对话复验 3 个 `node --check` 和独立单测全部通过，MCP 分支验收通过。
+- 前端续做轮次已完整返回，严格只新增 `public/task-board.js`、`public/task-board.css`、`scripts/task-board-frontend-unit.js`。主对话复验语法和独立 MiniDOM 契约单测均通过，前端分支验收通过。
+- Hook 两个白名单文件的语法、独立单测，以及真实 service+lifecycle 跨模块冒烟均通过；但子对话仍处于运行态且未返回终态。尝试发送“停止修改并直接汇报”被 cc-web 以 `target_running` 拒绝，未打断其活动 turn。
+- Hook 收尾阶段持续高 token 运行且文件仍有变化；确认原生 `abort` 只中断目标 turn 后，定向结束该 Hook turn。会话与文件均保留，三路 pending reply 全部转为 ready。
+- 对 Hook 最终文件重新执行语法、独立单测和真实 service+lifecycle 跨模块冒烟，全部通过；三个独立实现分支正式验收完成，进入第四个集成对话阶段。
+- 已创建第四个集成对话 `c053ad60-c5d7-4480-a3ef-a118fa81b13d`，reply request `af555b18-177f-4d41-b2da-bb18e211e848`。中央接线文件仅由该对话独占，明确禁止重启生产服务和创建额外工作对话。
+- 集成对话已完成规划/契约及三个模块的第一轮阅读，继续核对独立单测与现有接线点；当前 `lastError=null`，尚未修改中央文件。
+- 集成对话已通过 codebase-memory 函数级定位并用 `rg` 交叉核验会话 IO、WebSocket 分发、Codex App 生命周期、MCP tools/list/call 及前端导航入口；仍处于只读设计阶段，中央文件保持未改。
+- 集成对话首轮在 `contextCompaction` 时空结束，未修改中央文件；已向同一对话续发精简指令并恢复运行，没有创建替代对话。续做轮次正在重载必要模块上下文，`lastError=null`。
+- 集成续做轮次完成服务端与生命周期入口核对后，已开始用 `FileChange` 修改 `server.js`；这是中央文件首次解冻写入，当前仍未启动或重启任何服务。
+- 集成对话已修改 `server.js`、`lib/ccweb-mcp-server.js`、`public/index.html`、`public/app.js`，完成生产服务实例、WS/MCP/生命周期桥接及前端面板/开关初步接入；主对话复验三份中央 JS 的 `node --check` 均通过，生产服务仍未重启。
+- 集成 turn 在文件稳定后出现无活动，已定向中断；cc-web 随后自动重新接管同一 Codex 线程并以新运行态继续，未新建对话。续跑已进入 `scripts/regression.js`，现有中央补丁全部保留。
+- 集成对话完成全部接线与专项修正：前端返工移除伪“新建任务”和刷新按钮、改为继承现有主题变量、将任务跟踪开关收敛为输入区上方 28px 透明单行；集成层仅删除 `public/app.js` 中失效的 `createSession` 适配器。
+- 语法检查、前端/服务与 MCP/生命周期独立单测、隔离集成测试、`timeout 60s npm run regression` 与 `git diff --check` 全部通过，完整回归输出 `Regression checks passed.`。
+- Firefox 153.0.3 已完成 washi/carbon、1440×900/500px 四组真实浏览器验收：主题色随主题切换，伪按钮数量为 0，跟踪开关可开关，状态管理、归档/恢复与窄屏横向滚动正常。
+- 浏览器与隔离服务已自然关闭，无端口或 WebDriver 残留；四个工作对话均已结束，准备执行生产重启门禁。
+- 用户提供真实页面截图后确认首轮视觉验收结论错误：任务跟踪控件虽为 28px，却在输入区上方独占一行；同时“会话优先级”没有任何生产写入入口，仅由测试夹具构造。已撤销 Phase 4/5 完成结论并中止生产重启。
+- 已退回原前端、状态服务和集成对话：前端删除 priority 全部界面/协议，服务删除无来源字段与过滤，集成负责把 `#task-tracking-control` 移入 `.chat-controls` 并重新执行真实浏览器验收。最终结论由主对话直接核对，不再以子对话口头报告代替验收。
+
+### Test Results
+| Test | Expected | Actual | Status |
+|------|----------|--------|--------|
+| 工作区基线 | 识别已有改动并保护用户内容 | 初始化前 tracked worktree clean | PASS |
+| 集成语法与独立单测 | 中央 JS 语法及三个模块测试通过 | 全部退出码 0 | PASS |
+| 隔离集成与完整回归 | 集成链路和既有功能无回归 | `Task board integration checks passed.`；`Regression checks passed.` | PASS |
+| 真实浏览器验收 | 亮暗主题、桌面窄屏与核心交互通过 | Firefox 四组视口/主题证据通过 | PASS |
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+| init-session.sh 不支持 --help，误建规划目录 | 复用并改写为正式计划，未删除文件 |

.planning/2026-08-11-help/task_plan.md

@@ -0,0 +1,72 @@
+# Task Plan: 独立任务看板功能
+
+## Goal
+在不破坏现有会话功能的前提下，实现可选加入任务池的任务看板、状态 MCP 与 cc-web 生命周期 Hook，并完成集成回归、视觉验收和安全重启。
+
+## Current Phase
+Phase 4
+
+## Phases
+
+### Phase 1: 完成规划与基线检查
+- [x] 固化功能边界、共享接口和互斥文件范围
+- [x] 建立并审查执行计划与 TODO CSV
+- [x] 创建并启动 Trellis 任务，完成 PRD、技术设计与上下文配置
+- [x] 记录现有工作区与测试基线
+- **Status:** complete
+
+### Phase 2: 并行完成三个独立实现对话
+- [x] 前端对话仅实现 `public/task-board.*` 与独立单测
+- [x] MCP 对话负责 `lib/task-board-service.js`、MCP 适配模块与独立单测
+- [x] Hook 对话仅实现生命周期模块与独立单测
+- **Status:** complete
+
+### Phase 3: 汇总并审查三路产物
+- [x] 等待三个对话全部完成并收集回复
+- [x] 检查文件冲突、接口契约与独立性
+- **Status:** complete
+
+### Phase 4: 创建集成对话并完成接线
+- [x] 创建第四个集成对话
+- [ ] 接入现有 server、MCP、WebSocket 与页面入口
+- [x] 保持普通对话默认不进入任务池
+- [ ] 删除无数据来源的会话优先级，并将跟踪开关并入现有会话控制栏
+- **Status:** in_progress
+
+### Phase 5: 运行集成回归与视觉验收
+- [ ] 执行 `node --check`、三个独立单测和 `timeout 60s npm run regression`
+- [ ] 使用隔离测试服务和真实浏览器验证看板交互与响应式
+- [ ] 核对现有核心功能无回归
+- [ ] 由主对话对照真实页面亲自复核控制栏单行布局与功能来源
+- **Status:** pending
+
+### Phase 6: 审核重启条件并重启服务
+- [ ] 调用 `ccweb_list_conversations(status=running)`，仅排除来源 ID `56bb82c6-4fa3-4cb8-bb84-6969e6547d3a`
+- [ ] 确认四个工作对话均 idle，且 pending replies 无 waiting/delivering
+- [ ] 满足条件后执行 pm2 restart ccweb --update-env
+- [ ] 完成服务健康检查
+- **Status:** pending
+
+### Phase 7: 清理临时跟踪并交付
+- [ ] 完成最终变更审查与测试摘要
+- [ ] 同步并清理 TODO CSV
+- [ ] 交付功能、风险和验证结果
+- **Status:** pending
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+| 三个实现对话只新增或修改各自边界内文件，中心文件由第四个集成对话统一修改 | 避免共享工作区并发写冲突 |
+| 使用 cc-web 自身生命周期事件，不自动注入用户 Codex Hook | 保持功能独立并避免污染项目配置 |
+| 任务跟踪默认关闭，从看板创建的会话默认开启 | 普通简单对话不进入任务池 |
+| 归档采用软归档，与任务状态分离 | 可恢复、可审计，不影响原会话历史 |
+| MCP 对话拥有共享 TaskBoardService；Hook 通过依赖注入调用它 | 消除两个后端对话重复实现状态模型的风险 |
+| 共享契约固定在 `.trellis/tasks/08-11-task-board/info.md` | 三个并行对话与第四个集成对话有同一事实来源 |
+
+## Errors Encountered
+| Error | Resolution |
+|-------|------------|
+| init-session.sh 将 --help 当成任务名并创建 2026-08-11-help | 保留该目录并改写为本任务正式规划，避免未经确认删除或移动文件 |
+| 首次计划审查发现并行边界、共享服务、Trellis 和重启门禁不够具体 | 已补 PRD、技术契约、明确文件所有权、验证命令和会话检查入口 |
+| Hook 子对话收尾阶段长时间高 token 运行且不返回终态 | 独立测试通过后使用现有 WebSocket `abort` 仅中断该目标 turn；其最终文件随后重新验收通过 |
+| 首轮视觉验收只检查跟踪控件自身高度，未检查它是否占用独立行；同时未追查会话优先级的数据生产入口 | 判定首轮验收无效并中止重启；重新打开集成阶段，删除伪优先级并要求跟踪控件与既有会话控制同一行 |

.planning/2026-08-11-unify-ccweb-message-reply/findings.md

@@ -0,0 +1,91 @@
+# 发现与决策：统一 ccweb 消息回传接口
+
+## 需求
+
+- 将 `ccweb_send_message` 与 `ccweb_request_reply` 合并为一个公开工具。
+- 使用显式参数选择单向投递或自动回传。
+- 优化工具描述、目标对话提示和来源续跑提示。
+- 保留旧调用的兼容能力，但不让新模型继续在两个公开工具间选错。
+- 本次需要实际落地并通过回归。
+
+## 已确认事实
+
+- `requestCrossConversationReply()` 当前只是
+  `sendCrossConversationMessage(..., { expectReply: true })` 的薄包装。
+- 正式 MCP 定义位于 `lib/ccweb-mcp-server.js`，Codex App 备用定义位于
+  `server.js`，两处描述已出现漂移。
+- `ccweb_create_conversation` 已经使用 `requestReply` 参数，现有公开 API 风格不一致。
+- `buildCrossConversationRuntimeText()` 当前只标注来源标题和 ID，不携带是否自动回传。
+- `buildCrossConversationReplyAutoRunText()` 当前只包含目标标题和返回正文，缺少
+  `requestId`、原始请求和完整性检查指令。
+- 真实会话中曾对明确要求“完成后汇报/最终验收”的任务误用
+  `ccweb_send_message`；同一会话此前使用过 `ccweb_request_reply`，说明问题不是工具
+  不可发现，而是选择语义不够强。
+- 真实会话还出现过目标返回“完成定位、准备修改”后仍继续工作的情况；提示词可降低
+  概率，但“turn 完成是否等于任务完成”仍是协议级风险。
+
+## 并发与工作树基线
+
+- 当前另有两个非本对话的 `running` 对话：任务看板、失败插入卡片。
+- `server.js`、`lib/ccweb-mcp-server.js`、`scripts/regression.js` 已有未提交改动，均与本任务重叠。
+- `.planning/.active_plan` 指向 `2026-08-11-help`，`.trellis/.current-task` 指向
+  `.trellis/tasks/08-11-task-board`；不得覆盖。
+- 本任务使用 `.planning/2026-08-11-unify-ccweb-message-reply/` 保存独立上下文。
+- 已创建 Trellis 任务 `.trellis/tasks/08-11-unify-ccweb-message-reply/`，但不会执行
+  `task.py start`：全局 `.trellis/.current-task` 正被另一个运行中对话使用。后续实施与
+  审查子代理必须显式读取本任务路径，不能依赖全局 current-task。
+
+## 技术决策
+
+| 决策 | 理由 |
+|---|---|
+| `replyMode` 必填、无默认值 | 避免模型省略参数后静默失去回传 |
+| 值为 `one_way`、`return_and_continue` | 名称直接表达真实副作用，不暗示同步等待 |
+| 公开列表移除旧工具，内部 dispatcher 保留别名 | 兼顾新调用清晰度与存量线程兼容 |
+| 共享工具定义为单一来源 | 防止 MCP 与备用 dynamic tools 文案/Schema 漂移 |
+| 回传模式目标提示禁止手工回复 | 防止同一结果重复投递或形成环路 |
+| 来源续跑先判断完整性 | 防止把“已返回”误判成“已完成” |
+| 直接复用 `CCWEB_MCP_TOOLS` 生成 Codex App 备用定义 | `server.js` 已导入正式工具清单，无需新增第三个契约模块 |
+
+## 最新代码基线
+
+- `server.js` 顶部已导入 `{ TOOLS: CCWEB_MCP_TOOLS }`，但
+  `codexAppCommunicationDynamicTools()` 仍手写重复定义。
+- 最小单一来源方案：正式定义继续留在 `lib/ccweb-mcp-server.js`；该模块同时导出
+  reply mode 常量；`server.js` 从 `CCWEB_MCP_TOOLS` 按通信工具白名单筛选并添加
+  `namespace: 'ccweb'`。
+- 此方案同时统一所有既有通信工具描述，且不会把 task-board 工具意外加入备用列表。
+- 公开 TOOLS 不能兼作唯一调用 allowlist；需要单独的 hidden legacy name 集合，避免
+  已缓存 `ccweb_request_reply` 的旧线程在到达 dispatcher 前失败。
+- `scripts/regression.js` 现有 `assertCcwebListConversationsScopeContract()` 会从
+  `server.js` 的手写 dynamic tool 源码中截取 `ccweb_list_conversations` schema；改成
+  单一来源后该断言也必须改为调用 `codexAppCommunicationTools()` 并比较正式定义，
+  否则正确的去重实现会被旧静态断言误报。
+- 当前任务看板对话不是陈旧运行标记：其 `codexapp-state.json` 持续更新，正在做隔离
+  浏览器验收并已发现新增列 `description` 契约缺陷。它后续可能修改 `server.js` 与
+  `scripts/regression.js`，本任务必须继续等待其生产改动闭环。
+
+## 待验证
+
+- 现有测试是否直接断言公开工具数量或旧工具名称。
+- Codex App 备用 dynamic tool 路径是否仍有实际回归覆盖。
+- 旧线程调用已不在工具列表中的旧名称时，内部 MCP dispatcher 是否仍可接收。
+- 原始请求内容加入 pending 状态是否涉及持久化格式兼容。
+- 正式 MCP 的 `tools/call` 是否在公开 TOOLS 之外保留隐藏旧名（必须保留）。
+
+## Trellis 规范结论
+
+- 仓库只声明 backend/frontend 两层；本任务属于 backend + 跨层协议，不需要加载前端组件规范。
+- backend error handling 基本为空，现有 `mcpToolError` 行为应作为事实规范保留。
+- backend quality 的已填内容仅针对部分 JSON 预览，与本任务无直接约束。
+- `cross-layer-thinking-guide.md` 要求显式定义工具 Schema → dispatcher → pending 状态 →
+  目标运行提示 → 来源续跑提示的完整数据流，并在入口集中校验。
+- `code-reuse-thinking-guide.md` 明确要求相同常量/定义单一来源；支持让 Codex App
+  备用工具列表直接派生自正式 MCP 定义。
+
+## 资源
+
+- `server.js`：跨对话发送、回传、运行提示、dynamic tool 定义。
+- `lib/ccweb-mcp-server.js`：正式 MCP 工具清单与输入 Schema。
+- `scripts/regression.js`：跨对话 MCP 端到端回归。
+- `README.md`：公开工具说明。

.planning/2026-08-11-unify-ccweb-message-reply/progress.md

@@ -0,0 +1,104 @@
+# 进度日志：统一 ccweb 消息回传接口
+
+## 2026-08-11
+
+### 阶段 1：隔离规划与并发基线
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 23:34 CST
+- 已执行：
+  - 读取 `planning-with-files`、`todo-list-csv` 与 Trellis 工作流。
+  - 运行 planning session catchup。
+  - 检查工作树、全局 planning/Trellis 指针和运行中对话。
+  - 确认目标文件存在并发重叠，决定不覆盖全局活动指针。
+  - 建立 8 步 `update_plan`。
+  - 创建独立 Trellis 任务 `08-11-unify-ccweb-message-reply`，保留现有全局 current-task。
+  - 写入 PRD、技术设计、研究基线和 implement/check 上下文；Trellis validate 通过。
+  - 并行派发计划审查、影响面研究、测试研究和并发基线研究。
+  - 计划审查已通过；采纳“不重启、旧 pending 兼容、双公开列表测试”建议。
+  - 确认 `server.js` 已导入正式 `CCWEB_MCP_TOOLS`，决定直接复用而非新增契约文件。
+  - 并发审计确认核心安全范围：只改跨对话提示/发送/回传、dynamic tools、工具定义、
+    README 和对应回归；保留 task-board、children scope 与 failed-insert 改动。
+
+### 阶段 2：契约与失败测试
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 23:45 CST
+- 已执行：
+  - 固化 `replyMode`、公开工具、旧调用兼容和单一来源方向。
+  - 影响面与测试研究已汇总，Trellis context 再次校验通过。
+  - 测试审计确认正式 MCP tools/call 需要隐藏旧名 allowlist，已补入 PRD 与测试设计。
+  - 契约固化完成，新增 `scripts/ccweb-message-reply-unit.js` 静态契约测试。
+  - `node --check scripts/ccweb-message-reply-unit.js` 通过。
+  - `node scripts/ccweb-message-reply-unit.js` 以退出码 1 按预期红灯；首个失败为
+    公开 `TOOLS` 仍暴露 `ccweb_request_reply`。
+  - 复核四个核心文件 SHA-256，均与隔离基线一致。
+- 已创建/修改：
+  - `.planning/2026-08-11-unify-ccweb-message-reply/task_plan.md`
+  - `.planning/2026-08-11-unify-ccweb-message-reply/findings.md`
+  - `.planning/2026-08-11-unify-ccweb-message-reply/progress.md`
+  - `.trellis/tasks/08-11-unify-ccweb-message-reply/`（由 Trellis 脚本创建）
+
+## 测试结果
+
+| 测试 | 预期 | 实际 | 状态 |
+|---|---|---|---|
+| 尚未执行 | 先完成失败测试设计 | 待执行 | pending |
+| `node --check scripts/ccweb-message-reply-unit.js` | 语法通过 | 退出码 0 | passed |
+| `node scripts/ccweb-message-reply-unit.js` | 当前实现红灯 | 退出码 1，旧工具仍公开 | expected-fail |
+| `node --check lib/ccweb-mcp-server.js` | 语法通过 | 退出码 0 | passed |
+| `node --check server.js` | 语法通过 | 退出码 0 | passed |
+| `node scripts/ccweb-message-reply-unit.js`（实现后） | 契约转绿 | 退出码 0 | passed |
+| `node scripts/regression.js --target session-preview-metadata` | 共享定义定向回归通过 | 退出码 0 | passed |
+| `npm run regression`（第 1 次） | 暴露兼容提示缺口 | 缺少“子对话”措辞，退出码 1 | fixed |
+| `npm run regression`（第 2 次） | 暴露提示强度缺口 | 缺少连续“自动回传”措辞，退出码 1 | fixed |
+| `npm run regression`（第 3 次） | 完整回归通过 | 退出码 0，约 49 秒 | passed |
+| `git diff --check` | 无空白错误 | 退出码 0 | passed |
+
+### 阶段 3：实现与文档
+
+- **状态：** complete
+- **开始时间：** 2026-08-12 00:00 CST
+- 当前约束：任务看板对话仍在运行且与四个核心文件重叠；进入生产修改前继续等待其退出，
+  避免覆盖并发改动。
+- 并发收敛后已完成：
+  - 正式 MCP 只公开带必填 `replyMode` 的 `ccweb_send_message`。
+  - Codex App fallback 从正式定义派生，旧名只保留隐藏调用兼容。
+  - 发送运行时、pending `originalRequest`、两类目标提示和来源续跑提示已实现。
+  - README 与新接口一致。
+  - 专项契约测试已转绿。
+
+### 阶段 4：验证与交付
+
+- **状态：** complete
+- **开始时间：** 2026-08-12 00:26 CST
+- **完成时间：** 2026-08-12 00:34 CST
+- 已完成：
+  - `node --check lib/ccweb-mcp-server.js` 与 `node --check server.js` 均通过。
+  - 专项契约测试与 `session-preview-metadata` 定向回归均通过。
+  - 完整 `npm run regression` 在 60 秒门禁内通过，耗时约 49 秒。
+  - `git diff --check` 通过。
+  - 独立 Trellis 验收通过，无阻塞、重大或中等问题，且未修改文件。
+  - 确认未覆盖任务看板、children scope、failed-insert-card 与移动端按钮既有改动。
+  - 按约束未重启生产 `ccweb` 服务，未修改全局 planning/Trellis 指针。
+
+## 错误日志
+
+| 时间 | 问题 | 次数 | 处理 |
+|---|---|---:|---|
+| 2026-08-11 23:34 CST | 目标文件存在并发未提交修改 | 1 | 记录基线，先研究后精确合并 |
+| 2026-08-11 23:39 CST | full-history fork 不能同时覆盖 agent_type | 1 | 改用无历史 fork 并显式传入路径和目标 |
+| 2026-08-11 23:43 CST | 跨多文件补丁上下文不精确 | 1 | 拆成小型精确补丁完成同步 |
+| 2026-08-11 23:47 CST | 第二次跨多文件补丁仍因上下文漂移失败 | 2 | 后续坚持单文件或稳定锚点补丁 |
+| 2026-08-12 00:27 CST | 完整回归发现来源续跑缺少旧“子对话”标识 | 1 | 恢复兼容措辞后专项通过 |
+| 2026-08-12 00:28 CST | 完整回归发现目标提示“自动把结果回传”不够直接 | 1 | 收紧为连续短语“自动回传结果” |
+
+## 5 问重启检查
+
+| 问题 | 回答 |
+|---|---|
+| 当前在哪？ | 任务已完成并进入交付状态 |
+| 接下来去哪？ | 无剩余实施步骤 |
+| 目标是什么？ | 统一公开发送工具并可靠区分是否自动回传 |
+| 已了解什么？ | 见 `findings.md` |
+| 已完成什么？ | 隔离规划、契约、失败测试、生产实现、文档、完整回归与独立验收均已闭环 |

.planning/2026-08-11-unify-ccweb-message-reply/task_plan.md

@@ -0,0 +1,93 @@
+# 任务计划：统一 ccweb 消息回传接口
+
+## 目标
+
+将公开跨对话发送能力统一为一个 `ccweb_send_message`，通过必填 `replyMode`
+显式选择单向投递或自动回传；旧 `ccweb_request_reply` 仅保留内部兼容，并补齐
+目标提示、来源续跑上下文、文档与回归覆盖。
+
+## 当前阶段
+
+已完成：专项与完整回归、独立审查及交付清理均已闭环
+
+## 可验收步骤
+
+1. [x] 建立隔离规划并审查并发改动基线（DONE）
+2. [x] 固化统一消息接口契约与兼容策略（DONE）
+3. [x] 补充统一接口与提示语义的失败回归测试（DONE）
+4. [x] 实现单一公开工具与共享工具定义（DONE）
+5. [x] 实现模式化目标提示与来源续跑上下文（DONE）
+6. [x] 更新文档并保留旧工具内部兼容（DONE）
+7. [x] 运行专项与完整回归并修复问题（DONE）
+8. [x] 复核变更并清理临时规划清单（DONE）
+
+## 阶段
+
+### 阶段 1：隔离规划与并发基线
+
+- [x] 记录现有脏工作树与重叠文件
+- [x] 确认并发对话边界，不覆盖全局活动计划
+- [x] 完成计划文档审查
+- **状态：** complete
+
+### 阶段 2：契约与失败测试
+
+- [x] 定义必填 `replyMode`、返回结构与兼容行为
+- [x] 先补覆盖正式 MCP/备用工具列表、参数校验、内部旧别名和提示语义的失败测试
+- **状态：** complete
+
+### 阶段 3：实现与文档
+
+- [x] 统一正式 MCP 与 Codex App 备用定义
+- [x] 接入模式化目标提示和带关联信息的来源续跑提示
+- [x] pending reply 保存原始请求，并兼容旧状态缺失该字段
+- [x] 保留旧工具内部路由兼容但不再公开
+- [x] 更新 README
+- **状态：** complete
+
+### 阶段 4：验证与交付
+
+- [x] 运行语法、专项测试和完整回归
+- [x] 审查仅本任务引入的差异，确认未覆盖并发改动
+- [x] 清理 TODO CSV 并闭环计划
+- **状态：** complete
+
+## 关键问题
+
+1. 如何在不破坏现有持久对话的前提下停止公开 `ccweb_request_reply`？
+2. `replyMode` 如何强制模型在每次调用时明确选择，而不是依赖危险默认值？
+3. 如何让目标对话知道是否自动回传，并防止重复手工回传？
+4. 来源自动续跑时需要携带哪些关联信息，才能判断返回是否完整？
+5. 如何复用单一工具定义，避免正式 MCP 与备用定义再次漂移？
+
+## 已作决定
+
+| 决定 | 理由 |
+|---|---|
+| 公开接口只保留 `ccweb_send_message` | 真实会话已出现两个相似工具选错的情况 |
+| `replyMode` 为必填枚举且无默认值 | 强制调用者显式判断是否需要结果 |
+| 初始值采用 `one_way` / `return_and_continue` | 对应当前真实能力，避免虚假的同步等待语义 |
+| 旧 `ccweb_request_reply` 仅内部兼容 | 保护已经加载旧工具定义的存量线程 |
+| 目标提示按模式生成 | 自动回传模式必须禁止手工重复回传 |
+| 来源续跑提示携带 requestId、原请求与完整性检查规则 | 降低多请求混淆和把中间结果当完成的风险 |
+| 不修改 `.planning/.active_plan` 与 `.trellis/.current-task` | 它们正被其他运行中对话使用，覆盖会造成并发污染 |
+
+## 错误与风险记录
+
+| 错误或风险 | 次数 | 处理 |
+|---|---:|---|
+| 工作树已有大量他人改动，且目标文件重叠 | 1 | 先记录基线，等待/协调重叠对话，采用精确补丁 |
+| 全局 planning/Trellis 活动指针属于其他任务 | 1 | 使用独立规划目录和显式任务路径，不覆盖指针 |
+| 使用 full-history fork 同时指定 explorer 角色被拒绝 | 1 | 改为 `fork_turns: none` 并显式提供完整研究上下文 |
+| 一次跨多文件补丁因上下文不精确失败 | 1 | 拆成小型精确补丁，不重复原调用 |
+
+## 完成标准
+
+- 新工具清单不再公开 `ccweb_request_reply`。
+- `ccweb_send_message.replyMode` 必填，并覆盖两种模式。
+- 旧工具名仍可经内部路由执行自动回传。
+- 目标运行提示明确模式，自动回传模式禁止手工重复回传。
+- 来源续跑提示包含关联信息和完整性判断要求。
+- 正式 MCP、Codex App 备用定义与 README 一致。
+- 相关专项测试和完整回归通过，`git diff --check` 通过。
+- 不执行生产 `ccweb` 服务重启。