# R2.6 任务报告

## 目标与来源

- 来源：[HWLAB #2510](https://github.com/pikasTech/HWLAB/issues/2510)。
- 固定诊断 trace：`ae0181ba9a18bad2a561157d312c3692`。
- 目标是在纯 Kafka + SSE 架构内定位重复首层，禁止文本指纹去重、HTTP/数据库补洞、第二失败通道和新开真实 run。

## 离线证据与根因

- OTel 有界读取显示固定 trace 只有 `hwlab-cloud-api POST /v1/agent/chat` 一个 503 span；权威上游类型是 `schema-invalid`，错误层为 `agentrun`。
- 失败时段候选 session `ses_d5511238-e999-48a8-a93e-eb3c3f93e540` 仍为 `messageCount=0`、`lastTraceId=null`，更新时间停在失败前。
- `hwlab-cli kafka inspect order` 对该 session 完整扫描既有 `agentrun.event.v1` 与 `hwlab.event.v1` 后，两侧 `matchedCount=0`；共享 refresh handoff、Web reducer 与 DOM projection 也均为 0。没有读取事件值或 dump，也没有新建真实运行。
- 因此首个重复环节不在 AgentRun event、HWLAB bridge、Kafka、SSE 或 reducer。失败发生在 durable admission 之前；Web 的 `projectLocalAdmissionFailure` 却伪造了一个 `workbench-local` terminal trace event，所以出现“运行记录 1 events”。同一错误随后又由 assistant 正文、synthetic timeline Error 与诊断摘要各显示一次。

## 修复方案

- 新增 pre-admission typed failure classifier。分类 authority 只读取正式 `failureKind`、显式 `retryable`、状态码和 correlation 字段；`rollout-in-progress` 只接受 AgentRun 权威 typed code，不按时间、503 或文案推断。
- 保留 `failureKind/reason/retryable/userMessage/recoveryAction`，并透传 Workbench trace、upstream trace、run、command、dispatch intent 与 dispatch stage；尚未创建的 identity 显式为 `null`，admission state 为 `rejected-before-durable-dispatch`。
- 覆盖 rollout、manager/service、admission/policy、runner capacity、provider/profile、Secret、image、workspace/materialization、lease/idempotency、dispatcher/runtime 与 unknown 类型。固定 `schema-invalid` 分类为不可重试的 `dispatcher-runtime-misconfigured`。
- Web 不再把 HTTP admission rejection 制造成 trace/Kafka event，不再写假 terminal turn/session authority；只保留一个由稳定 assistant message/failure identity 拥有的失败正文。timeline Error 和诊断摘要依据 `failureIdentity + primaryPresentation + lifecycle` 收敛，不比较显示文本。
- 诊断折叠区继续展示类型、恢复动作和 correlation；正式 Kafka failure 的原始 `runnerTrace.events` 与 raw HWLAB Event 数据不做删除或过滤。
- optimistic session running authority 改为 HTTP durable admission 成功后才建立，避免未接纳请求污染 session 状态。

## 验证

- `bun test internal/cloud/code-agent-dispatch-failure.test.ts`：3/3 通过，覆盖 rollout transient、固定 schema-invalid permanent、provider/profile permanent 与 unknown 下钻。
- `bun test internal/cloud/server-agent-chat.test.ts --test-name-pattern 'preserves typed schema-invalid'`：通过；503 响应保留完整 typed fields/correlation，且没有 false running/failed owner write。
- `bun test web/hwlab-cloud-web/scripts/workbench-realtime-runtime.test.ts`：34/34 通过；固定 trace fixture 只有 `UserMessage + AssistantPart`，无 synthetic Error、无 local trace event；正式 Kafka failure 的两条 raw event 保持不变。
- `bun run check:tsc`：通过 Web source scan、Vite/Vue build 与 source-shape 检查。
- `git diff --check`：通过。

## 待完成验收

- 当前交付边界是未合并 PR，不手工部署或触发 CI/CD。PR 合并后应等待 GitHub webhook → mirror → PAC → CI/CD 自动发布，再用原 Workbench 入口验证失败正文只出现一次、无“运行记录 1 events”，并核对诊断字段；完成该运行面证据后再关闭 R2.6/#2510。
