Merge pull request #488 from pikasTech/fix/code-agent-partial-result-tests

fix: harden Code Agent result lifecycle

docs/reference/cloud-workbench.md

@@ -150,6 +150,19 @@ workspace；除非 Pod 重建、Codex supervisor 重启、用户显式清空对
 可用时优先使用；server 内存 session 因 Pod/replica 切换丢失时，只要本地 session 未过期，
 刷新页面不得要求用户重新登录。
 
+恢复出的历史消息如果携带 `traceId`，前端必须先对 `/v1/agent/chat/result/<traceId>` 做
+终态归一，再回放 `/trace`。旧的 `running` 消息不能只因为 localStorage restore 被降级成
+`source` 后停留在“处理中”文本；如果后端 result 已经完成，消息卡片必须替换为真实
+reply/blocker/session/providerTrace。如果 trace 只显示 `result:*` 终态事件而消息仍未完成，
+也必须立即查 result，而不是把 `Code Agent result is ready for short-connection polling.` 当成
+最终回复或让用户手工重试。
+
+Cloud Workbench 的 Code Agent 单元测试不得依赖真实 token、真实公网 provider 或真实硬件。
+前端状态机测试应使用固定 fixture/mock fetch 覆盖 submit accepted、result completed、result
+failed、session busy、partial timeout、trace compacted、SSE 断流和页面恢复；后端测试应使用
+fake Codex app-server client 覆盖长耗时和缺失 `turn/completed`。真实 DEV `--live` smoke 只用于
+发布后读写边界明确的验收，不作为 PR 默认回归测试。
+
 ## Lightweight Checks
 
 Use the existing lightweight checks unless a task explicitly authorizes a

docs/reference/code-agent-chat-readiness.md

@@ -208,12 +208,18 @@ Workbench trace 对已知 JSON-RPC gateway 响应应按普通 tool call 展示
 
 Workbench 与 Code Agent 的用户请求必须是短连接 submit + 短连接 result/trace 轮询；浏览器或 cloud-web 不应持有一次长 HTTP 请求等待整个 Codex turn 结束。`POST /v1/agent/chat` 返回 `202` 后，前端轮询 `/v1/agent/chat/result/<traceId>` 获取终态，并用 `/v1/agent/chat/trace/<traceId>` 刷新可视 trace。
 
+Code Agent backend 的 completed 语义只能来自真实 Codex app-server `turn/completed` 成功事件。`item/agentMessage/delta`、`item/completed`、已有 assistant 文本、transport close 或 activity idle timeout 都不能单独升级成 `status: "completed"`。如果已经收到部分 assistant 文本但没有收到 `turn/completed`，终态必须是 timeout/partial blocker，并保留 trace、session、thread、partial output 摘要和可重试提示；Workbench 只能显示“部分回复/超时”，不能标 DEV-LIVE reply pass。
+
 cloud-web 同源代理必须把短连接语义原样转发给 cloud-api，至少包括 `Prefer: respond-async`、`X-HWLAB-Short-Connection` 和 `X-Trace-Id`。如果这些 header 在 cloud-web 层被过滤，cloud-api 会把同一个请求当成长同步请求处理，用户入口会表现为 `17666` 卡住或代理超时，而 `17667` 直连 cloud-api 正常。此类问题应先比对同一 trace 在 `17666` 与 `17667` 的 submit 行为，再修代理 header 透传，而不是调大前端等待时间。
 
 `/v1/agent/chat/result/<traceId>` 是终态摘要接口，不是完整 trace 下载接口。它可以携带压缩后的 `runnerTrace` 窗口用于传输保活，但 Workbench 用户界面不得把该窗口显示为“压缩窗口”或“显示全部”。只要结果或轮询快照声明 `eventsCompacted=true`，前端必须自动请求 `/v1/agent/chat/trace/<traceId>` 并用完整 trace 替换可视事件线；回放完成前只能显示“完整 trace 回放中/当前已载入”状态。result 响应仍必须保留 `eventCount`、`lastEvent`、`providerTrace`、`threadId/sessionId` 和终态 reply/blocker；完整 trace 只能从 `/v1/agent/chat/trace/<traceId>`、复制 JSON 或下载 trace 入口取得。默认 result trace 窗口上限由 `HWLAB_CODE_AGENT_RESULT_TRACE_EVENT_LIMIT` 控制；不要把数百个大 chunk 原样塞进 result 响应，避免 cloud-web 代理层或浏览器 fetch 把“正常执行中的大响应”表现成 503、非 JSON 或空响应。
 
 result 轮询的 408/425/429/5xx、浏览器 timeout、非 JSON 或空响应应按“可恢复传输抖动”处理：前端先拉取一次 trace 刷新活性，再带退避继续轮询，只有后端返回结构化 terminal blocker、真实终态失败，或 trace 按无新事件 idle timeout 超时，才向用户显示失败。只要 `/trace` 仍显示新事件或 `waitingFor` 仍在推进，就不能把一次 result poll 失败标成“Code Agent API 错误”并停止。
 
+Workbench 的 trace 展示不是终态真相。只要 trace 中出现 `result:completed`、`result:failed`、`result:canceled`、`session:session_busy` 这类 terminal event，或浏览器从本地状态恢复出带 `traceId` 的非终态消息，前端必须再请求 `/v1/agent/chat/result/<traceId>` 做 result reconciliation，并用 result 的 reply/blocker/session/providerTrace 替换消息卡片。仅回放 `/trace` 不能把旧 running 消息改成完成，也不能把 `Code Agent result is ready for short-connection polling.` 当作用户可见最终回复。
+
+长耗时和前后端协同缺陷必须优先用 mock/fixture 复现，不得把真实 token 调用作为日常回归测试。后端单元测试使用 fake Codex app-server JSON-RPC client 模拟 `thread/started`、`turn/started`、assistant delta、command output、`turn/completed` 缺失、transport close 和 idle timeout；前端测试使用固定 `/result`、`/trace`、EventSource、localStorage fixture 验证 result reconciliation、刷新恢复、transient poll error 和 compact trace 回放。真实 `--live` Code Agent smoke 只作为显式授权的 DEV 验证，不进入默认 PR 单元测试路径。
+
 Windows 侧 skill、编译器、脚本工具和多参数命令都应走同一个通用传输模式，不新增某个工具的专用 wrapper 子命令：
 
 - 工作目录优先用 wrapper 的 `--cwd <windows path>` 或脚本内 `Set-Location -LiteralPath <path>` 表达，不要在 prompt 里拼 `cmd /c "cd ... && ..."`。