docs: 固化助手进度事件合同

docs/reference/spec-v01-agentrun-mgr.md

@@ -169,7 +169,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
 | `status` | run/command 当前聚合状态，只能由 command state 和 terminal_status 推导。 |
 | `terminalStatus` | `completed`、`failed`、`blocked` 或 `cancelled`；没有 terminal event 时为 `null` 或 equivalent running 状态。 |
 | `completed` / `terminalSource` | `completed=true` 只能来自 terminal completed；`terminalSource` 标明来自 `terminal_status` event、run record 或暂无 terminal。 |
-| `reply` / `finalResponse` | 从 `assistant_message` 聚合的最终用户可见文本；若存在 `replyAuthority=true` 或 `final=true` 的 `assistant_message`，必须取最后一条作为 authoritative reply。没有 authoritative final 时，result 可以 fallback 到 terminal 前最后一条非空 assistant 文本，但必须在 `finalResponse` 暴露 `seq`、`source`、`replyAuthority`、`final`、`textTruncated` 和 `outputTruncated`，让消费侧知道它是可见性 fallback，不是 backend final authority。没有 terminal completed 时不得伪造 completed reply。 |
+| `reply` / `finalResponse` | 只从 durable `assistant_message` 聚合最终用户可见文本；`assistant_progress` 永远不参与 reply、fallback 或 final authority。若存在 `replyAuthority=true` 或 `final=true` 的 `assistant_message`，必须取最后一条作为 authoritative reply。没有 authoritative final 时，result 可以 fallback 到 terminal 前最后一条非空 durable assistant 正文，但必须在 `finalResponse` 暴露 `seq`、`source`、`replyAuthority`、`final`、`textTruncated` 和 `outputTruncated`，让消费侧知道它是可见性 fallback，不是 backend final authority。没有 terminal completed 时不得伪造 completed reply。 |
 | `finalResponseAuthority` / `finalResponseFallback` / `needsContinuation` / `completionEvidence` | 必须在 result 顶层暴露最终回复权威性。`finalResponseAuthority` 只能是 `authoritative`、`fallback` 或 `missing`；terminal completed 但没有 authoritative final 时，`needsContinuation=true`，`completionEvidence` 必须说明原因并给出同 session 的 `sessions send` 恢复入口。 |
 | `finalAssistantSeq` / `finalAssistantSource` | 必须指向 result 本次选中的 assistant event；长 trace、steer 或 progress snapshot 场景不能让早期 assistant row 继续冒充最终摘要。 |
 | `finalAssistantTextTruncated` / `finalAssistantOutputTruncated` | 必须原样暴露被选中 assistant event 的截断标记；被选中的最终摘要截断时，消费侧应继续读 events 或 trace，而不是把截断隐藏成完整 final。 |
@@ -182,7 +182,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
 | `liveness` | 查询时派生的 supervisor 活性快照，不写入 durable event。必须暴露 `phase`、`active`、`lastSeq`、`lastEventAgeMs`、`lastActivity`/`lastCommandActivity`、`timeoutBudget`、lease/heartbeat 摘要和可执行恢复动作。`lastActivity` 必须包含 `sourceSeq`、`eventId`、`activityKind`、`observedAt` 和 `ageMs`，用于按 id/seq drill-down；默认只给有界摘要，不展开 stdout、runnerTrace、完整 tool command 或 raw event。`timeoutBudget` 必须按无响应空闲时间计算，`executionPolicy.timeoutMs` 是 idle budget，不是 turn wall-clock hard timeout；只要 backend notification、assistant/tool/event、command output 或等价 activity 持续刷新，就必须重置 idle 起点并继续等待。该对象必须暴露 `timeoutKind="idle"`、`hardTimeout=false`、`idleStartedAt`、`idleElapsedMs`、`lastActivityAt`、`lastActivitySeq`、`elapsedMs`、`remainingMs` 和 `state`（如 `within-budget`、`approaching-idle-timeout`、`idle-timed-out`、`terminal`）。`phase` 至少区分 `waiting-runner`、`waiting-model`、`waiting-model-output`、`waiting-tool`、`waiting-tool-output`、`idle-after-tool`、`runner-stdio-inactive`、`transport-disconnected`、`runner-heartbeat-stale` 和 `terminal`，避免调用方只能用外层超时猜测 backend 状态。终态失败/阻塞时仍必须保留恢复动作，例如 inspect result、read events/trace、continue same session、split task，而不是返回空数组。 |
 | `steerDelivery` | 仅在查询 `type=steer` command result 时出现。必须说明 steer 是否已被 runner ack、是否已转发并被 backend `turn/steer` RPC 接受、目标 `targetCommandId`、是否观察到 target command 后续事件，以及“steer command completed 不等于 target turn 已产生后续 assistant/tool 输出”的语义。 |
 
-`assistant_message` partial、`command_output` 存在、stdout 非空、backend transport close 或 idle timeout 都不能单独让 result 进入 `completed`。
+`assistant_progress`、`command_output` 存在、stdout 非空、backend transport close 或 idle timeout 都不能单独让 result 进入 `completed`。
 
 `GET /api/v1/sessions/:sessionId` 作为 session status 入口，必须在存在 active/last run 时透出同一套 `liveness` 和 `supervisor` 摘要；该摘要是观测辅助，不能替代 command terminal、run terminal 或 raw events 的事实来源。
 

docs/reference/spec-v01-backend-adapter.md

@@ -38,7 +38,7 @@ Backend adapter 的第一阶段实现应吸收 HWLAB v0.2 已验证的 Codex std
 | --- | --- | --- |
 | Codex app-server JSON-RPC stdio | `internal/cloud/codex-stdio-session.ts`、`internal/cloud/codex-stdio-session-turn-state.ts` | 支持 `initialize`、`thread/start`、`thread/resume`、`turn/start`，并处理 app-server client request；未知请求要记录 unsupported error，不能静默等待。 |
 | completed 判定 | `docs/reference/code-agent-chat-readiness.md` | 只有 Codex turn terminal completed 且 assistant reply 可聚合时才输出 completed；assistant delta、item completed、stdout 或 transport close 不能单独完成。 |
-| assistant stream 和 trace | `internal/cloud/code-agent-trace-store.ts`、`internal/cloud/codex-stdio-session-turn-state.ts` | assistant delta 只能作为 stream/progress 证据；长输出过程中可以输出有界 `assistant_message.source=agent-message-delta-progress` 快照，但 `replyAuthority=false`，不能作为 authoritative final；每个非空 completed `agentMessage` item 必须输出一个 `assistant_message` event，保留 `itemId` 和顺序；`item/agentMessage:started`、`item/agentMessage:completed` 这类 lifecycle 不得额外持久化为 `backend_status`，避免同一消息在 Web/CLI trace 中重复渲染；最终 result reply 必须优先来自最后一个 completed `agentMessage` item，不能把 commentary/progress delta 与 final response 直接串接。若 provider 未产生 completed/final assistant，manager result 的可见性 fallback 与 `finalResponse` 标记规则以 [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md#result-envelope) 为准。event 必须保留 `threadId`、`turnId`、session 摘要和 redacted backend metadata。 |
+| assistant stream 和 trace | `internal/cloud/code-agent-trace-store.ts`、`internal/cloud/codex-stdio-session-turn-state.ts` | assistant delta 只能作为 stream/progress 证据；长输出过程中的有界累计快照必须使用独立 `assistant_progress` event，标记 `source=agent-message-delta-progress`、`progress=true`、`replyAuthority=false`、`final=false` 和 `durableText=false`，不能伪装成 durable assistant 正文；每个非空 completed `agentMessage` item 必须输出一个 `assistant_message` event，保留相同 `itemId` 和顺序。消费侧按 `itemId` 与 `sourceSeq` 把 progress 更新为 completed 正文，不得按文本相等去重。`item/agentMessage:started`、`item/agentMessage:completed` 这类 lifecycle 不得额外持久化为 `backend_status`；final seal 只引用已持久化正文，不复制文本。最终 result reply 必须优先来自最后一个 completed `agentMessage` item，不能把 commentary/progress delta 与 final response 直接串接。若 provider 未产生 completed/final assistant，manager result 的可见性 fallback 与 `finalResponse` 标记规则以 [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md#result-envelope) 为准。event 必须保留 `threadId`、`turnId`、session 摘要和 redacted backend metadata。 |
 | command/tool output bounded | `docs/reference/code-agent-chat-readiness.md`、`web/hwlab-cloud-web/app-trace.ts` | `tool_call` 和 `command_output` 必须记录状态、摘要、字节数、截断标记；完整大输出只能通过后续 log/artifact 引用。 |
 | provider/profile 隔离 | `internal/cloud/code-agent-contract.ts` | `codex`、`deepseek`、`minimax-m3` 与 `dsflash-go` 共享同一 backend kind，但必须使用 profile-scoped SecretRef、model/base-url/config/model catalog 和 writable runtime home。 |
 | Secret redaction | `internal/cloud/code-agent-trace-store.ts` | `OPENAI_API_KEY`、auth/config、token、password、kubeconfig、URL credential 不得进入 event、result、log 或 health。 |
@@ -61,7 +61,8 @@ Registry 只表达能力和选择边界，不读取 Secret 值。Manager 负责
 Adapter 输出给 runner 的 event 类型至少包括：
 
 - `backend_status`：backend 启动、模型/profile、能力和阶段状态，不包含 Secret 值。
-- `assistant_message`：模型输出的用户可见 assistant 文本。Codex app-server 的 `item/agentMessage/delta` 只能作为流式过程证据或缺少 completed item 时的兜底；adapter 可以为长 delta 输出有界 progress 快照，必须标记 `source=agent-message-delta-progress`、`progress=true`、`replyAuthority=false` 和 `final=false`。一旦收到 completed `agentMessage` item，adapter 必须为每个非空 completed item 输出一条 `assistant_message`，并用 `itemId`、`messageIndex`、`messageCount`、`replyAuthority` 和 `final` 标明顺序与最终 reply authority。最终 result reply 必须优先以最后一个 `replyAuthority=true` / `final=true` 的 `assistant_message` 为准，避免把 commentary/status/progress 堆入 authoritative final response；无 authoritative final 时的 manager fallback 必须显式暴露 `finalResponse.source`、`finalResponse.seq` 和截断标记。
+- `assistant_progress`：模型输出的用户可见累计进度快照。必须保留 `itemId`、`sourceSeq`、`source=agent-message-delta-progress`、`progress=true`、`replyAuthority=false`、`final=false` 和 `durableText=false`；不得进入 result reply，也不得被 final seal 或 terminal 复制为第二份正文。
+- `assistant_message`：模型输出的 durable 用户可见 assistant 正文。Codex app-server 的 `item/agentMessage/delta` 只能产生 `assistant_progress`，不能作为 `assistant_message` fallback。一旦收到 completed `agentMessage` item，adapter 必须为每个非空 completed item 输出一条 `assistant_message`，并用 `itemId`、`messageIndex`、`messageCount`、`replyAuthority` 和 `final` 标明顺序与最终 reply authority。最终 result reply 必须优先以最后一个 `replyAuthority=true` / `final=true` 的 `assistant_message` 为准，避免把 commentary/status/progress 堆入 authoritative final response；无 authoritative final 时的 manager fallback 必须显式暴露 `finalResponse.source`、`finalResponse.seq` 和截断标记。
 - `tool_call`：工具调用摘要和 redacted 参数。
 - `command_output`：stdout/stderr 或命令输出摘要。
 - `diff`：代码变更摘要或 patch 片段；必须受长度限制。

docs/reference/spec-v01-cli.md

@@ -150,7 +150,7 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
 - `sessions send --dry-run` 必须全路径 non-mutating，只返回将提交给 manager 的有界计划和 manager 根据当前 session 状态可判断的 `decision`，不得创建 session、PVC、run、command 或 runner job。`sessions turn` / `sessions steer` 已删除且不兼容；不得作为隐藏 alias、低层诊断入口、默认 help、恢复建议或调度者工作流重新出现。
 - `sessions cancel` 通过 Session control 取消 active command 或 run；`sessions read` 写入 reader cursor，使 terminal session 从默认 ps 中消失。
 - `sessions output` 与 `sessions trace` 是输出和 trace 的唯一 CLI 查询入口；不得新增 `queue output` 或 `queue trace` 兼容命令。
-- `sessions output` 与 `sessions trace` 默认必须按渐进披露输出低噪声 JSON：只展示 `assistant_message` 与 `tool_call`/`error` 摘要，`command_output`、`backend_status`、raw event、runnerTrace 和大 stdout/stderr 只进入 `suppressedEvents` 计数与 bytes，不得默认展开正文。需要查看工具输出、backend_status 或原始 event 时，必须通过默认摘要中的 `detailCommands`，或显式使用 `--seq <n>`、`--event-id <id>`、`--item-id <id>`、`--include-output`、`--full`/`--raw` 做定点展开；默认摘要生成的 `detailCommands` 必须带上能定位该 event 的最小 `--after-seq`/`--limit` hint，避免按 id 拉详情时重新扫描长 trace。这样保证默认不爆上下文，同时按 id/seq 可完整追溯。
+- `sessions output` 与 `sessions trace` 默认必须按渐进披露输出低噪声 JSON：展示有界 `assistant_progress`、durable `assistant_message` 与 `tool_call`/`error` 摘要，并按 `itemId + sourceSeq` 明确进度到完成态的生命周期；不得把 progress 当作 final reply。`command_output`、`backend_status`、raw event、runnerTrace 和大 stdout/stderr 只进入 `suppressedEvents` 计数与 bytes，不得默认展开正文。需要查看工具输出、backend_status 或原始 event 时，必须通过默认摘要中的 `detailCommands`，或显式使用 `--seq <n>`、`--event-id <id>`、`--item-id <id>`、`--include-output`、`--full`/`--raw` 做定点展开；默认摘要生成的 `detailCommands` 必须带上能定位该 event 的最小 `--after-seq`/`--limit` hint，避免按 id 拉详情时重新扫描长 trace。这样保证默认不爆上下文，同时按 id/seq 可完整追溯。
 
 ## 配置与 Secret 边界