chore: rebuild release package and commit updates

2026-07-13 10:13:04 +08:00
parent dd466a69b5
commit 141a266f34
19 changed files with 1066 additions and 35 deletions
--- a/.planning/ccweb-drop-diagnosis/findings.md
+++ b/.planning/ccweb-drop-diagnosis/findings.md
@@ -0,0 +1,107 @@
+# ccweb 频繁掉线诊断发现
+
+## 当前状态（2026-07-11 22:29 +08:00）
+
+- `ccweb` 当前为 `online`，PID 1606383，单实例 fork 模式。
+- PM2 累计重启次数为 60，说明不是一次性偶发。
+- 当前进程 `pm_uptime=1783779949754`，约在 22:25:49 启动，距检查仅约 3 分半钟，符合用户所述“刚才掉线”。
+- 当前进程内存约 76 MiB、CPU 3.1%；主机可用内存约 4.8 GiB、磁盘使用率 32%，检查时不存在资源耗尽。
+- 主机已持续运行 119 天，说明刚才并非整机重启。
+
+## 日志时间线
+
+- 2026-07-11 22:25:49，PM2 明确记录 `Stopping app:ccweb`，随后进程以 `code [0] via signal [SIGINT]` 正常退出，并在同一秒重新启动、恢复 online。
+- 同日 11:21:10、12:25:37 也出现完全相同的“主动停止 → SIGINT/0 → 立即启动”序列。
+- 近期大量记录都是该形态；这更像 `pm2 restart/reload/stop` 一类外部管理动作，不像应用崩溃或被系统 OOM Kill。
+- `ccweb-out.log` 只看到重复的 `CC-Web server listening on 0.0.0.0:8002`，对应多次启动，没有本次异常堆栈。
+- `ccweb-error.log` 最后修改时间是 2026-06-15；其中确有一次 V8 堆达到约 2 GiB 后 OOM，但它不是 7 月 11 日这次掉线的直接原因。
+
+## 自动策略与系统反证
+
+- PM2 配置：`watch=false`、`cron_restart=null`、`max_memory_restart=null`；因此本次不是文件监听、定时器或 PM2 内存阈值触发。
+- 同一时间窗口的内核日志没有 OOM、Killed process 或段错误记录。
+- 当前 8002 端口由 ccweb 进程正常监听，本地 HTTP 检查返回 200，耗时约 2.6 ms。
+- 项目源码、用户 crontab、系统 cron/timer 未发现自动执行 `pm2 restart/reload ccweb` 的配置；交互式 shell 历史也没有可归因的匹配记录。
+- PM2 日志只记录了动作结果，不记录发起 restart 的客户端 PID/会话，因此现有日志能确认“外部管理动作”，但无法可靠归因到具体用户或具体对话。
+- 检查时除当前对话外还有一个 English 项目的 codexapp 对话处于 running；本轮没有执行服务重启。
+
+## 频率与可归因证据
+
+- 2026-07-01 至 2026-07-11 共发生 19 次 `Stopping app:ccweb`；逐次退出全部为 `code=0, signal=SIGINT`，没有一次属于异常退出。
+- 分布：7 月 1 日 3 次、2 日 6 次、3 日 1 次、5 日 4 次、7 日 2 次、11 日 3 次。
+- Codex 本地会话记录能确认至少 7 月 7 日的两次重启确实由会话内显式执行 `pm2 restart ccweb --update-env` 触发，说明“开发/代理完成改动后手动重启”是真实存在的来源。
+- 截至当前证据，尚未定位 7 月 11 日 22:25:49 这一次的具体发起会话。
+
+## 初步结论（已被用户澄清推翻）
+
+以下判断仅保留为调查过程记录，不是最终结论：
+
+- 本次连接失败的直接原因是 ccweb 在 22:25:49 被外部 PM2 管理动作主动重启，单实例在停止/启动窗口内中断现有连接。
+- “最近频繁掉线”的主因也是频繁主动重启，而不是当前应用持续崩溃；7 月以来已发生 19 次同类主动重启。
+- 现有 PM2 日志缺少调用者审计，因此无法仅靠当前日志追溯 22:25 这一次是谁发起。
+- 独立风险：6 月 15 日曾发生 V8 堆 OOM，且 PM2 主日志已约 157 MiB；两者值得后续单独治理，但与本次中断无直接因果关系。
+
+## 用户澄清后的因果修正
+
+- 用户确认：网页先打不开，随后由用户人工执行 PM2 重启恢复。
+- 因此 22:25:49 的 `Stopping app` / `SIGINT` 只能证明恢复动作，不能解释故障起因。
+- 现阶段真正待查的是：旧 PID 1163252 在退出前为何无法响应 HTTP；由于重启前没有请求延迟、事件循环延迟、堆内存和活跃句柄快照，历史日志证据存在明显缺口。
+- `home-cc-web` 代码索引状态为 ready（3072 节点、7430 条边），可继续按函数和调用链定位阻塞候选。
+
+## 初步代码风险面
+
+- 主服务是单 Node.js 事件循环；`server.js` 在请求和 WebSocket 热路径中存在大量同步文件系统调用。
+- `plog` 每次记录都同步执行 `statSync`、可能的 rotate/unlink/rename，再 `appendFileSync`；若日志路径所在文件系统短时阻塞，会拖住整个 HTTP 服务。
+- `sendSessionList` 同步扫描会话目录并读取/解析会话元数据；会话数量或单文件体积增大时，可能形成明显事件循环停顿。
+- `handleMessage` 同步读取并 base64 编码附件、同步创建输入/输出文件；大附件会放大停顿和堆占用。
+- `wsSend` 直接在主线程 `JSON.stringify(data)`；历史 6 月 15 日 OOM 栈也落在 V8 `JsonStringify`，说明超大对象序列化是已发生过的真实风险，而非纯理论。
+- 这些是“具备卡死能力”的候选路径；尚不能仅凭静态代码断定 22:25 具体命中了哪一条。
+- `plog` 有 38 个调用方，属于广泛热路径；每次调用都同步触盘。
+- `wsSend` 有 48 个调用方且统一同步序列化；只要某次 payload 意外携带超大对象，整个服务会在 `JSON.stringify` 期间停止处理新 HTTP 请求。
+- `sendSessionList` 有 15 个调用方；每次都同步遍历所有会话文件，并逐文件 `statSync`，小于阈值时还会整文件 `readFileSync + JSON.parse + normalizeSession`。
+- 因此“网页整体打不开”更符合主事件循环被长任务/同步 I/O 占住，而不是单个 WebSocket 会话故障；但仍需用运行态日志与文件规模交叉验证。
+- 当前代码已有单会话/消息截断上限：会话持久化默认 10 MiB、加载上限 32 MiB、列表元数据整文件解析阈值 512 KiB，tool result 持久化默认截到 32 KiB。它们能降低风险，但无法消除“很多会话逐个同步读取”或某个发送前对象尚未裁剪的阻塞。
+- 在常见目录范围内暂未找到 `logs/process.log`；需要继续确认 `APP_DIR` 实际值。若结构化日志实际未落盘，正好解释了为什么本次只剩 PM2 生命周期日志而没有故障前业务事件。
+- 已确认源码运行目录就是 `/home/cc-web`，结构化日志实际位于 `logs/process.log`；此前检索未命中属于检索结果异常，现已纠正。
+- 当前 `sessions/` 有 112 个 JSON 会话文件，总体积约 64 MiB；最大单文件约 4.09 MiB，多份文件超过 1 MiB。
+- 用与 `sendSessionList` 等价的同步读取策略做只读基准，一次扫描实测约 5.99 秒（user 2.07 秒、sys 1.35 秒）。在这段时间内单线程 Node 无法响应 8002 上的任何 HTTP 请求。
+- `sendSessionList` 又会被 turn complete、消息处理、终止、导入等至少 15 类路径触发；若短时间连续触发广播，会形成数秒级阻塞叠加，足以解释“网页完全打不开但 PM2 进程仍在线”。这是目前证据最强的根因候选。
+- `process.old.log` 在 22:24:01 完成约 2 MiB 轮转，距离 22:25:49 人工重启约 1 分 48 秒；需要检查轮转前后事件是否出现会话列表广播/完成风暴。
+- 22:15–22:26 的结构化日志共有 1089 条 `codex_app_notification_unrouted`；其中 991 条是 `item/agentMessage/delta`，另有 32 条 item completed、30 条 item started。
+- 这些通知集中指向同一个找不到路由的 app-server thread/turn；频率约 1–2 条/秒，部分时刻同一毫秒多条。
+- `handleCodexAppNotification` 对每一条未路由通知都会同步调用 `plog` 后返回；因此这 1089 条通知直接转化为 1089 次主线程 `statSync + appendFileSync`，并导致故障前日志轮转。
+- 当前最可能的故障模型：孤儿/失路由 app-server 流式通知持续灌入，同步日志 I/O 占用事件循环；同时任何 session list 广播还会触发一次全量同步扫描。两者叠加时，HTTP 请求长时间排队，网页表现为不可达。
+- 仍需确认该 orphan thread 来自哪个会话，并复测扫描耗时以排除首次冷缓存/Node 启动成本夸大。
+- 已确认 thread `019f5186…` 对应当时正在运行的 English 会话 `a21170ff…`，并有对应 22:13 启动的 Codex rollout；它不是无主外部进程，而是 ccweb 对一个真实活跃会话丢失了 runtime 路由。
+- 热缓存下连续 5 次等价会话扫描为 188–243 ms，每次读取约 22 MiB；因此先前约 5.99 秒结果包含 Node 冷启动/系统抖动，不能把单次会话扫描独立定为根因。
+- 200 ms 级同步扫描仍会造成可感知卡顿，连续触发仍可叠加，但本次更直接的异常是“活跃 thread 持续产出通知，ccweb 却无法路由”。
+- 修正后的高概率链路：活跃会话 runtime 路由丢失 → 大量流式通知被判为 unrouted → 每条同步写日志并轮转；同时 UI 收不到该会话事件。是否足以让静态 HTTP 也超时，仍需结合路由查找复杂度和当时其它事件判断。
+- 对应 thread 的未路由状态不是运行中途才丢失：首次出现在 22:13:44（thread 启动/MCP startup 阶段），一直持续到 22:25:49 人工重启，共 1054 条，集中在同一个 turn。
+- `findCodexAppRouteByRuntime` 本身只做 route 查找、一次未路由 turn 认领尝试和 child map 查询，不是高复杂度扫描；真正异常是 thread 从创建开始就没有被成功注册/认领到 `activeCodexAppTurns`。
+- 因而更准确的描述是“新活跃 thread 路由建立失败”，而不是“已建立路由后来丢失”。重启后的 recovery 能重新挂接该会话，解释了为什么重启会恢复。
+- 未路由认领逻辑要求同时满足：方法在 adoptable 白名单、通知含 threadId+turnId、持久化会话文件已经能按 threadId 命中；任一条件不满足都会继续丢弃并写日志。
+- 一旦认领成功，代码会写入 `activeCodexAppTurns`、持久化状态并记录 `codex_app_unrouted_turn_adopted`；故障窗口完全没有该事件，说明认领条件始终未满足。
+- 当前会话文件只在父级 `collabAgentToolCall` 输入中引用该 child thread，并不能通过 `getRuntimeSessionId` 匹配；后续确认这是原生子代理映射注册缺口，不是父会话 threadId 持久化竞态。
+- 常规 route 查找会线性遍历 `activeCodexAppTurns` 两次（threadId、turnId），但活跃会话数量很小，不足以解释整体失联。
+- 已定位决定性放大器：`isCodexAppAdoptableRuntimeMethod` 明确把 `item/agentMessage/delta`、item started/completed 等高频通知列为可认领方法。
+- 每条可认领但未路由通知都会进入 `findCodexAppSessionByThreadId`；该函数同步 `readdirSync` 全部会话文件，并逐个调用 `loadSession(sessionId)`，直到找到 thread 或扫描到底。
+- 故障 thread 当时无法命中，因此 991 条 delta 基本都会扫描全部 112 个会话、约 64 MiB 数据。数量级约为 991 × 64 MiB ≈ 63 GiB 的同步读取/解析压力，集中在约 11 分钟内并占用 HTTP 主线程。
+- 这条链路可以同时解释三个现象：PM2 仍显示 online、结构化日志仍断续增长、网页却无法打开——进程没死，只是事件循环被同步扫描持续压满。
+- 目前只差核对 `loadSession` 的精确读取策略并做一次“thread miss”只读基准，即可给出高置信结论。
+- `loadSession` 确认通过 `safeReadSessionJson` 执行 `statSync + readFileSync + JSON.parse`，默认允许读取到 32 MiB；当前所有 112 个会话文件都低于该上限，因此 miss 时会整批完整读取和解析。
+- “thread miss”全量读取/JSON 解析的 5 次热缓存基准为 604–840 ms，每次实际读取 60.8 MiB；这仍未包含生产代码的 `normalizeSession` 成本，因此是保守下界。
+- 故障 thread 的 1054 条未路由通知覆盖约 725 秒，平均间隔约 0.69 秒，几乎等于一次全量扫描耗时。于是主线程形成连续循环：通知 → 60.8 MiB 同步扫描 → miss → 同步日志 → 下一通知。
+- 按 1054 次估算，累计同步读取量约 62.6 GiB；按实测下界累计阻塞时间约 637–885 秒，与 725 秒故障窗口同量级。这足以高置信解释整个 HTTP 服务无响应。
+- 根因已从“候选”提升为高置信：未路由高频通知触发无缓存、无退避的全量同步会话查找，压满 Node 事件循环。
+- 故障 thread 的 rollout 元数据确认它是父 thread `019f514d…` 在 English 会话中通过 `spawn_agent` 启动的 depth=1 原生子代理，任务名为 `inspect_drill_tests`。
+- 子 thread ID 在父 ccweb 会话 JSON 中只出现在 `collabAgentToolCall` 的 `agentThreadId` 输入路径，不是父会话的 runtime session ID；因此 `findCodexAppSessionByThreadId` 扫遍所有父会话也必然 miss。
+- 子代理通知本应通过 `ccwebMcpChildThreads` 路由。该映射依赖父级 `collabAgentToolCall` 通知中的 `receiverThreadIds`；同步函数在数组为空时直接返回。spawn 初期若还没有 receiverThreadIds，而后续状态未及时补发/处理，子 thread 会永久没有映射。
+- 最终根因链路：原生子代理 spawn 后 child thread 映射未及时建立 → child 高频 delta 无路由 → 每条 delta 错误进入父会话全量同步查找 → 60.8 MiB/次、约 0.6–0.84 秒/次 → Node 主事件循环被持续占满 → 网页打不开；人工重启通过 recovery 重建状态后恢复。
+
+## 最终结论
+
+- 本次并非进程崩溃或系统 OOM，而是 Node 主事件循环被同步工作持续占满；用户的 PM2 重启是恢复动作。
+- 触发源是 English 会话通过 `spawn_agent` 创建的子代理 `inspect_drill_tests`。child thread 映射未建立，1054 条子代理通知从 22:13:44 起持续走未路由回退。
+- 回退逻辑对每条高频 delta 同步扫描 112 个会话文件并完整读取/解析 60.8 MiB；单次保守基准 604–840 ms，累计约 62.6 GiB、637–885 秒阻塞，和 725 秒故障窗口吻合。
+- 重启后 adoptable 未路由通知已归零；剩余 98 条仅为 rate-limit/status 类非认领通知，不再触发全量会话扫描。22:45 检查服务 online，HTTP 200，响应约 2.5 ms。
+- 修复应同时覆盖三层：spawn 时可靠登记 child thread 路由；未路由查找改为内存索引/负缓存并禁止每 delta 全盘同步扫描；未路由日志做聚合限频和异步写入。
--- a/.planning/ccweb-drop-diagnosis/progress.md
+++ b/.planning/ccweb-drop-diagnosis/progress.md
@@ -0,0 +1,22 @@
+# ccweb 频繁掉线诊断进度
+
+- 2026-07-11：开始只读诊断，已确认不执行重启或配置修改。
+- 2026-07-11 22:29：完成当前状态采样；发现 ccweb 刚在约 22:25:49 重启，PM2 累计重启 60 次。
+- 2026-07-11 22:34：完成 PM2 与应用日志初查；本次为外部触发的正常 SIGINT 重启，不是异常崩溃。
+- 2026-07-11 22:39：排除 watch、cron、PM2 内存阈值、内核 OOM 和端口故障；未发现自动重启脚本或定时任务。
+- 2026-07-11 22:43：统计 7 月以来 19 次均为 SIGINT/0 的主动重启；历史会话记录证实开发代理曾显式执行重启命令。
+- 2026-07-11 22:46：完成一分钟窗口会话审计与结论归纳；本轮未重启、未修改服务配置或业务代码。
+- 2026-07-11：用户澄清重启是故障后的人工恢复；已撤回“主动重启导致本次掉线”的因果判断，开始追查重启前无响应。
+- 2026-07-11：确认历史可观测数据不足以直接还原旧进程状态；代码索引可用，进入阻塞路径分析。
+- 2026-07-11：发现主线程同步日志、同步会话扫描/解析、同步附件处理和 WebSocket 大对象序列化等阻塞候选。
+- 2026-07-11：函数级调用面确认同步日志、全量会话列表和统一 WebSocket 序列化均处于高扇入路径。
+- 2026-07-11：核对会话体积阈值；初次常见目录检索未发现结构化 process.log，继续确认运行数据目录。
+- 2026-07-11：确认 112 个会话共 64 MiB，同步会话扫描一次约 5.99 秒；发现日志在故障前约 1 分 48 秒轮转。
+- 2026-07-11：故障窗口确认 1089 条未路由通知风暴，991 条为 agentMessage delta；每条都会同步写日志。
+- 2026-07-11：thread 归因到活跃 English 会话；热缓存会话扫描约 188–243 ms，修正此前 5.99 秒的过度归因。
+- 2026-07-11：确认 thread 自 22:13:44 创建起即未成功建立路由，直到 22:25:49 重启；排除路由查找本身的复杂度问题。
+- 2026-07-11：确认未路由认领依赖持久化 threadId 与 adoptable 方法；故障期间从未认领成功，竞态/worker 注册遗漏成为首要代码缺陷候选。
+- 2026-07-11：定位高频 delta 的全量同步会话扫描放大器；估算故障窗口产生约 63 GiB 读取/解析压力，能够解释整站无响应。
+- 2026-07-11：精确确认 loadSession 为完整同步读取/解析；miss 基准 604–840 ms，累计阻塞时间与整个故障窗口同量级，根因达到高置信。
+- 2026-07-11：确认故障 thread 是原生 spawn_agent 子代理；定位 child 映射注册缺口与错误回退到父会话全量扫描的完整因果链。
+- 2026-07-11 22:45：复核重启后无 adoptable 未路由风暴，服务 HTTP 200/约 2.5 ms；完成修正后的最终结论。本轮未改业务代码、未改配置、未重启。
--- a/.planning/ccweb-drop-diagnosis/task_plan.md
+++ b/.planning/ccweb-drop-diagnosis/task_plan.md
@@ -0,0 +1,26 @@
+# ccweb 频繁掉线诊断计划
+
+## 目标
+
+只读排查 ccweb 最近连接失败和频繁掉线的原因，形成可验证的时间线、根因判断与风险说明；不重启、不改配置、不改业务代码。用户已澄清 22:25 的重启是故障后的人工恢复动作，因此继续追查重启前网页无响应的原因。
+
+## 阶段
+
+- [完成] 1. 确认服务当前状态与最近重启次数
+- [完成] 2. 分析 ccweb 错误日志与退出时间线
+- [完成] 3. 核对系统资源、OOM 与端口/依赖异常
+- [完成] 4. 归纳根因、证据与处置优先级
+- [完成] 5. 修正因果关系并核对重启前可观测证据
+- [完成] 6. 定位可能阻塞 HTTP/事件循环的代码路径
+- [完成] 7. 对照会话与子进程活动评估高概率诱因
+- [完成] 8. 输出修正后的结论与可验证的监控缺口
+
+## 约束
+
+- 不执行 `pm2 restart`。
+- 不修改运行配置或项目代码。
+- 日志中的敏感信息不在答复中展开。
+
+## 错误记录
+
+- 初次结论误把人工重启当作掉线原因；用户澄清后已修正，重启仅是恢复动作。
--- a/.planning/ccweb-unrouted-notification-fix/findings.md
+++ b/.planning/ccweb-unrouted-notification-fix/findings.md
@@ -0,0 +1,50 @@
+# 调查结论
+
+## 2026-07-12 根因证据
+
+- `ccweb` PID 1606383 持续占满单个 CPU 核心，RSS 约 130 MiB，系统可用内存约 4.4 GiB。
+- `curl http://127.0.0.1:8002/` 能立即建立 TCP，但 8–10 秒无响应，符合事件循环阻塞而非端口未监听。
+- `logs/process.log` 每约 0.6 秒出现 `codex_app_notification_unrouted`，来源主要是三个 Codex App threadId。
+- 三个 threadId 均存在于当前 `sessions/*-run/codexapp-state.json`，却未恢复进内存路由映射。
+- `findCodexAppRouteByRuntime` 在内存命中失败后调用 `adoptCodexAppUnroutedTurn`。
+- `findCodexAppSessionByThreadId` 对每条未路由通知执行 `readdirSync(SESSIONS_DIR)`，再逐个 `loadSession`；当前 113 个会话 JSON 合计约 61.3 MiB。
+- 高频 delta × 同步全量扫描导致 Node 主线程单核 100%，所有 HTTP 请求饥饿。
+- PM2 error log 中的 V8 OOM 修改时间为 2026-06-15，是历史故障，不是当前直接原因。
+- 当未路由子线程通知停止后，未部署补丁的旧进程 CPU 从单核 100% 降至 0–2%，本地首页恢复为 HTTP 200/约 2.3 ms；这证明故障与通知风暴强相关，而非持续内存不足或端口问题。
+
+## 工作区约束
+
+- 用户已有修改：`public/app.js`、`public/style.css`、`scripts/regression.js`。
+- 现有未跟踪计划/任务目录属于其他工作，不得覆盖或删除。
+- `.trellis/.current-task` 当前指向 `00-bootstrap-guidelines`，另有 `07-11-subagent-card-metadata` 进行中；不得切换共享 current-task，以免干扰并发会话。
+- 项目要求重启前检查运行会话；只有除当前会话外没有其他 running 会话时才能重启。
+- 当前磁盘运行态检查只发现本对话 `4b9700f7-...` 的一个 `codexapp-state.json`，状态为 `running`；没有发现其他会话 run 目录或 classic PID 文件。最终重启前仍需再次复核。
+- 重启前通过运行中 ccweb 的内部 MCP `ccweb_list_conversations` 检查：仅当前对话为 `running`，其余全部为 `idle`，满足项目重启条件。
+
+## 部署验证
+
+- 执行 `pm2 restart ccweb --update-env` 成功，新 PID 为 1802039，PM2 restart 计数从 60 增至 61。
+- 启动日志出现 `ccweb_mcp_child_threads_recovered`，`restored=3`，证明真实恢复文件中的三个子线程路由被重建。
+- 连续 5 次本地 HTTP 探针均返回 200，后续最终探针约 3.6 ms。
+- 新进程 RSS 约 64 MiB，事件循环 P95 约 1.5 ms，短时 CPU 回落至 0–12%，没有持续占满单核。
+- 重启后的日志窗口仅包含 recovery/server_start 事件，没有新的 `codex_app_notification_unrouted` 风暴。
+
+## 项目上下文
+
+- Trellis 将项目识别为单仓库，规范层为 backend/frontend；本次只涉及 backend。
+- codebase-memory 项目 `home-cc-web` 索引状态为 `ready`，当前 3091 个节点、7446 条边。
+- 独立计划审查已通过；建议在实施记录中明确测试入口与重启检查。
+- 项目测试入口为 `npm run regression`（实际执行 `node scripts/regression.js`），服务入口为 `node server.js`。
+- backend 规范目录当前仍是模板状态，没有额外项目特定限制；本次重点遵守现有结构化 `plog`、同步 I/O 热路径规避和回归脚本惯例。
+- 预计修改位置：`recoverCodexAppTurnState`、`findCodexAppSessionByThreadId`、`adoptCodexAppUnroutedTurn`、`handleCodexAppNotification`，以及独立/现有回归脚本。
+- 当前 `codexapp-state.json` 只持久化父线程 entry；子线程 ID 仅间接存在于 `toolCalls[*].input.agentThreadId` 等协作工具数据中，`recoverCodexAppTurnState` 没有重建 `ccwebMcpChildThreads`。
+- `findCodexAppRouteByRuntime` 当前先调用父线程磁盘收养逻辑，再检查 `ccwebMcpChildThreads`；对子线程通知会先触发昂贵的父会话全盘扫描，路由顺序本身也需要调整。
+- 现有 `scripts/regression.js` 含用户未提交的“子代理卡片元数据”测试，修复必须追加且保留这些改动。
+- 真实恢复文件中，协作子线程以 `toolCalls[].name/kind = subAgentActivity` 持久化；`input.agentThreadId` 是路由键，`input.agentPath` 可作为恢复标签，`input.kind` 表示 started/interacted 等活动。
+
+## HAPI 对比
+
+- HAPI 的“归档”主要是会话生命周期操作：将 active session 断开并把 `metadata.lifecycleState` 设为 `archived`，支持后续 reopen；它不是专门为解决 ccweb 本次每条通知全盘扫描而设计。
+- HAPI 的归档确实能减少活动会话集合和实时订阅压力，但历史记录仍保留在存储/缓存层，因此只有配合索引化 SessionCache/SyncEngine 才能避免热路径扫描。
+- 对 ccweb 而言，未来增加归档有产品和容量管理价值，但不能替代当前 threadId 路由索引、恢复映射和负缓存修复。
+- 源码确认 HAPI `archiveSession` 调用 `rpcGateway.killSession` 后进入 `handleSessionEnd`；Hub 存储基于 `bun:sqlite`，`SessionCache` 维护内存态并以 `active` 作为权威运行标志。
--- a/.planning/ccweb-unrouted-notification-fix/prd.md
+++ b/.planning/ccweb-unrouted-notification-fix/prd.md
@@ -0,0 +1,27 @@
+# ccweb 未路由通知阻塞修复需求
+
+## 背景
+
+ccweb 重启后，仍在运行的 Codex App 协作子线程继续发送通知，但 `ccwebMcpChildThreads` 是进程内 Map，没有从 `codexapp-state.json` 恢复。通知无法命中路由，随后对每条 delta 同步遍历并解析全部会话 JSON，导致 Node 主线程单核 100% 和 HTTP 524。
+
+## 必须实现
+
+1. 恢复父会话状态时，从已持久化的协作 toolCalls 中重建足够的子线程路由信息，至少包含 child threadId、parentSessionId、parentThreadId、spawnToolId、状态和可用标签。
+2. 子线程内存路由必须在父线程磁盘收养之前判断，避免已知子线程也触发全盘扫描。
+3. 对真正未知的 threadId 增加有界负缓存，使高频 delta 在 TTL 内最多触发一次磁盘查找。
+4. `codex_app_notification_unrouted` 日志按 threadId/method 节流，保留诊断能力但不逐条写盘。
+5. 会话创建、更新、删除后应正确维护 threadId 索引或使缓存失效，不产生长期错误路由。
+6. 保留现有行为：父线程未路由通知仍可被收养；新产生的 collabAgentToolCall 仍可注册和更新子线程。
+
+## 测试要求
+
+- 先添加在旧实现上失败的回归断言，再实现最小修复。
+- 覆盖恢复态子线程映射重建、子线程优先路由、未知线程负缓存和日志节流。
+- 运行定向测试、`node --check server.js`、`npm run regression`。
+- 测试总超时不超过 60 秒。
+
+## 约束
+
+- 不覆盖 `public/app.js`、`public/style.css`、`scripts/regression.js` 中的用户现有改动。
+- 不通过增大堆上限或单纯重启掩盖根因。
+- 代码注释使用简体中文；日志不得包含敏感数据。
--- a/.planning/ccweb-unrouted-notification-fix/progress.md
+++ b/.planning/ccweb-unrouted-notification-fix/progress.md
@@ -0,0 +1,32 @@
+# 进度日志
+
+## 2026-07-12
+
+- 完成当前服务状态复核：确认 HTTP 超时、单核 100%、内存正常。
+- 确认未路由通知来自恢复态 Codex App 子线程。
+- 建立持久化修复计划、调查记录和验收标准。
+- 检查 Trellis 状态；由于共享 current-task 正被其他任务使用，决定不切换该全局指针。
+- 独立计划审查通过；根因、范围、验收标准与并发约束已固化。
+- 明确测试入口 `npm run regression`；codebase-memory 后续查询因传输关闭降级为本地精确读取。
+- 确认恢复状态没有直接持久化/重建子线程映射，且当前路由顺序会让子线程通知先走父线程磁盘扫描。
+- 初步运行会话检查只发现当前父会话处于 running；等待实现代理完成后将在重启前再次检查。
+- 首轮实现代理因检索耗时被中止；第二轮已追加失败回归契约并开始最小实现。
+- 对比 HAPI：归档是生命周期/活动集合管理能力，可降低长期压力但不是本次热路径问题的直接修复。
+- 实现代理已写入 `server.js` 核心补丁和回归契约；正在收口语法与定向验证。
+- 旧进程在通知风暴结束后暂时恢复 HTTP 200，但补丁尚未部署，仍需完成审查和重启验证。
+- 独立 check 代理已追加审查修正，等待其验证回报。
+- check 代理未及时结束，已中止；主线程复核确认负缓存与日志节流 Map 均有 1000 项上限和 30 秒 TTL/节流窗口。
+- 当前阶段：重新运行定向回归并处理问题。
+- 定向契约复跑通过，`server.js` 语法检查通过。
+- 当前阶段：执行完整回归与静态检查。
+- `timeout 60s npm run regression` 完整回归通过。
+- 当前阶段：最终差异审查与运行风险确认。
+- 重启前会话列表确认仅当前对话 running，其余全部 idle。
+- 执行 PM2 重启成功，新进程恢复 3 个子线程路由。
+- 连续 HTTP 探针均为 200；最终响应约 3.6 ms，CPU/内存/事件循环正常。
+- 重启后未发现新的未路由通知风暴，任务完成。
+- 回归契约已追加；旧实现缺少契约要求的索引、恢复与节流符号，必然失败。
+- 实现代理写入补丁后未及时结束，已中止并由主线程接管验证。
+- `node --check server.js` 通过。
+- `node scripts/regression.js --target codexapp-unrouted-routing` 通过。
+- 当前阶段：冷审查负缓存、日志节流和恢复一致性。
--- a/.planning/ccweb-unrouted-notification-fix/task_plan.md
+++ b/.planning/ccweb-unrouted-notification-fix/task_plan.md
@@ -0,0 +1,72 @@
+# ccweb 未路由通知阻塞修复计划
+
+## 目标
+
+修复 Codex App 子线程通知在进程恢复后无法路由、反复同步扫描全部会话文件并占满 Node.js 主线程的问题，恢复 ccweb HTTP 可用性并防止复发。
+
+## 阶段
+
+### Phase 1：建立任务上下文并固化根因与验收标准
+
+**Status:** complete
+
+### Phase 2：补充可复现的失败回归测试
+
+**Status:** complete
+
+### Phase 3：实现线程路由索引与恢复逻辑
+
+**Status:** complete
+
+### Phase 4：限制未路由通知的磁盘扫描与日志风暴
+
+**Status:** complete
+
+### Phase 5：运行定向回归测试并修正问题
+
+**Status:** complete
+
+### Phase 6：执行完整回归与静态检查
+
+**Status:** complete
+
+### Phase 7：审查变更与运行风险
+
+**Status:** complete
+
+### Phase 8：安全重启并验证本地/外部访问
+
+**Status:** complete
+
+## 验收标准
+
+- 恢复后，父线程及子线程通知均能通过内存索引命中，不对每个 delta 同步扫描全部会话 JSON。
+- 未知 threadId 的高频通知采用有界、缓存或节流策略，不造成日志风暴和单核持续 100%。
+- 回归测试覆盖恢复态子线程路由、未知线程负缓存/节流和现有通知路由行为。
+- 定向回归、完整回归和语法检查通过。
+- 重启前确认除当前会话外没有其他 running 会话；满足条件才重启。
+- 重启后本地 8002 健康响应，CPU 回落且日志不再持续刷未路由通知。
+
+## 决策
+
+- 不通过增大 Node.js 堆上限掩盖问题。
+- 优先建立 O(1) threadId 路由索引，并在恢复 `codexapp-state.json` 时重建子线程映射。
+- 为真正未知的通知增加负缓存/节流，避免重复全量磁盘扫描与逐条日志。
+- 保留用户已有未提交改动，不覆盖无关文件。
+
+## 错误记录
+
+| 错误 | 尝试 | 处理 |
+|---|---:|---|
+| `strace` 附加进程被系统拒绝 | 1 | 改用实时 CPU、HTTP 探针、日志频率和代码调用链交叉定位 |
+| codebase-memory `search_graph` 返回 `Transport closed` | 1 | 索引状态此前为 ready，但运行时传输关闭；按项目降级规则改用已确认的 qualified_name 与 `rg`/`sed` 精确读取 |
+| 更新计划文件时上下文定位失败 | 1 | 重新读取当前文件结构后使用更精确的补丁上下文 |
+| 首个实现代理在检索阶段长时间无补丁 | 1 | 中止该轮后复用同一代理，禁止 MCP，提供精确状态形状并收敛为本地 TDD 补丁任务 |
+| 第二轮实现代理写入补丁后未及时结束回报 | 1 | 中止代理并由主线程接管语法、定向与完整回归验证 |
+| 首次读取运行中 app-server 的本地 MCP token 使用了错误环境变量名 | 1 | 只列出环境变量键名确认实际为 `CC_WEB_CODEX_APP_MCP_TOKEN`，未输出 token 值，并成功完成会话状态检查 |
+| planning-with-files 完成检查首次报告 `0/0 phases` | 1 | 计划阶段原为中文编号列表；已改为检查脚本可识别的标准阶段标题与状态字段 |
+
+## 计划审查
+
+- 独立计划审查代理已通过，无阻断性问题。
+- 执行时显式记录测试命令、预计修改位置和重启前运行会话检查结果。
--- a/.planning/subagent-card-metadata/findings.md
+++ b/.planning/subagent-card-metadata/findings.md
@@ -0,0 +1,17 @@
+# 发现记录
+
+- 前端 `collabAgentStateEntries` 已读取 `label/title/name` 和 `description/summary/message`。
+- 当前渲染层仅把任务提示词和结果简介写入 DOM `title`，卡片正文没有显示简介。
+- 真实 Codex App `spawnAgent` 记录通常提供 `prompt`，但 `agentsStates` 在启动时为空，完成时 `name` 常为线程 ID。
+- 当前 `mergeCollabAgentTools` 只保留一个全局 `prompt`，需要把各次 spawn 的 prompt 写入对应代理状态。
+- 工作树开始时干净；已有 `.planning/codex-app-worker-timeout` 和根目录规划文件，不能覆盖。
+- Trellis 前端规范目前大多是模板，因此实施以现有 `public/app.js` / `public/style.css` 约定和回归测试为主要依据。
+- 原 Trellis 当前任务是 `00-bootstrap-guidelines`，本任务结束后需要恢复。
+- 样式集中在 `public/style.css` 的 `.collab-agent-*` 区块；需补齐 `min-width: 0` / `max-width: 100%` 收缩链，并为新增简介采用两行 clamp。
+- 回归入口是 `scripts/regression.js` 的 Codex App 子代理端到端段；现有测试验证事件链但未覆盖标题/简介展示语义。
+- mock 已提供两个子代理及不同 `name/role/summary`，可扩展为通用名称 + 不同 prompt，验证前端合并不串任务上下文。
+- 计划复审通过；实现范围保持前端与回归测试，不改后端协议、不重启服务。
+- 独立质量检查发现 UUID 正则仅覆盖 v1-v5，会漏掉 UUID v7；需要改为通用 UUID 形状判断。
+- 静态源码契约不足以证明多 spawn 行为；需要提取并执行实际纯函数源码，覆盖独立 prompt 与 wait/close 保留。
+- 后续状态会携带归一化空标题字段；合并时只有新状态含可读标题才允许覆盖旧标题。
+- 归一化 `entry.label` 可能由 prompt 派生，必须携带 `hasReadableSourceTitle` 标记区分协议标题和派生标题。
--- a/.planning/subagent-card-metadata/progress.md
+++ b/.planning/subagent-card-metadata/progress.md
@@ -0,0 +1,16 @@
+# 进度记录
+
+- 2026-07-11：完成现状定位与真实会话载荷核验。
+- 2026-07-11：确定紧凑双层卡片方向，开始计划审查。
+- 2026-07-11：创建 Trellis 任务、PRD，并配置实现/检查上下文。
+- 2026-07-11：首次计划审查发现标题优先级、空 prompt、悬浮信息共存和范围约束缺口，已修订并提交复审。
+- 2026-07-11：计划复审通过，进入回归断言设计。
+- 2026-07-11：并行完成样式和回归入口研究，准备交给 Trellis 实现代理测试先行落地。
+- 2026-07-11：实现标题选择、每代理 taskDescription、可见简介节点与窄屏样式，进入独立验证。
+- 2026-07-11：完整回归通过；独立检查提出 UUID v7 与行为测试覆盖问题，进入修正循环。
+- 2026-07-11：行为测试首次运行被多行源码契约误报阻断，已改用跨行正则。
+- 2026-07-11：复核发现状态更新覆盖可读标题边界，已改为条件更新并补回归。
+- 2026-07-11：进一步区分协议原生标题与 prompt 派生标题，避免派生 label 覆盖稳定协议标题。
+- 2026-07-11：语法、diff、完整 regression 和独立复核全部通过；进入交付清理。
+- 2026-07-11：最终 diff 与行号核验完成。实时服务在线但两次 5 秒请求无响应，环境无 Playwright/Chromium，因此未截图且未重启服务。
+- 2026-07-11：Trellis 规范沉淀判断：本次为局部子代理卡片行为，核心边界已固化在行为回归中，没有形成跨模块通用约定，不更新 `.trellis/spec/`。
--- a/.planning/subagent-card-metadata/task_plan.md
+++ b/.planning/subagent-card-metadata/task_plan.md
@@ -0,0 +1,78 @@
+# 子代理标题与简介展示计划
+
+## 目标
+
+在协作子代理卡片中稳定展示可读标题和任务简介，并确保多子代理合并、运行中与完成态都不丢失各自的任务上下文。
+
+## 视觉与交互方向
+
+- 视觉主张：延续现有深色紧凑工具卡，以清晰文字层级替代额外装饰。
+- 内容计划：第一行标题与状态，第二层展示两行任务简介，角色作为低权重辅助信息，结果继续保留在悬浮详情中。
+- 交互主张：保留卡片点击复制线程 ID、关闭按钮状态反馈和现有折叠行为，不新增装饰性动效。
+
+## 当前阶段
+
+已完成
+
+## 阶段
+
+### Phase 1: 建立实施计划并完成独立审查
+
+- **Status:** complete
+
+### Phase 2: 补充标题与简介的数据归一化回归断言
+
+- **Status:** complete
+
+### Phase 3: 实现每个子代理独立的标题与简介合并
+
+- **Status:** complete
+
+### Phase 4: 实现紧凑双层卡片渲染与样式
+
+- **Status:** complete
+
+### Phase 5: 运行语法检查与自动化回归测试
+
+- **Status:** complete
+
+### Phase 6: 检查真实页面效果并完成交付清理
+
+- **Status:** complete
+
+## 完成标准
+
+- 按 `label → title → nickname → name` 选择第一个非通用、非线程 ID 的协议标题。
+- 仅有线程 ID 或 `子代理` / `子代理 N` 等通用名称时，从该子代理自己的任务提示词生成稳定标题。
+- 每个子代理保留自己的简介，多子代理合并不会共用第一个提示词。
+- 无 prompt 时回退为短线程 ID，空字段不会导致异常。
+- 简介最多显示两行，完整简介挂在简介 DOM 的悬浮提示；运行结果保留在卡片容器的独立悬浮详情，两者不互相覆盖。
+- 现有状态、关闭、复制线程 ID 功能不回退。
+- 窄屏下标题、状态和关闭按钮不横向溢出。
+- 相关回归测试通过。
+
+## 回归场景
+
+1. 可读协议标题按字段优先级展示。
+2. 通用标题从各自 prompt 提炼。
+3. 多代理不同 prompt 的标题和简介不串联。
+4. 无 prompt 时回退短线程 ID。
+
+## 范围约束
+
+- 不新增依赖。
+- 不改变后端协议。
+- 不重启服务。
+
+## 错误记录
+
+| 错误 | 尝试 | 处理 |
+|---|---:|---|
+| 暂无 | 0 | - |
+| UUID v7 未被识别为线程式标题 | 1 | 扩展为通用 UUID 形状判断并补行为测试 |
+| 回归仅验证源码字符串契约 | 1 | 提取实际纯函数源码执行多 spawn / wait / close 用例 |
+| 新增集成契约按单行字符串匹配多行调用 | 1 | 改为允许空白与换行的正则匹配 |
+| 后续空标题字段覆盖首次可读协议标题 | 1 | 合并时无可读新标题则保留旧标题字段，并补行为回归 |
+| 多文件补丁缺少合法 hunk 边界 | 1 | 拆分为独立小补丁应用 |
+| prompt 派生 label 被误判为协议标题 | 1 | 归一化阶段携带标题来源标记并补行为回归 |
+| 规划文档阶段格式未被完成检查器识别 | 1 | 改为标准 Phase 三级标题与完成状态字段格式 |