docs: 固化 command result 长 trace 合同

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

@@ -158,9 +158,12 @@ 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` | 从 `assistant_message` 聚合的最终用户可见文本；若存在 `replyAuthority=true` 或 `final=true` 的 `assistant_message`，必须取最后一条作为 reply；没有这些标记时才按 legacy chunk 聚合。没有 terminal completed 时不得伪造 completed reply。 |
+| `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。 |
+| `finalAssistantSeq` / `finalAssistantSource` | 必须指向 result 本次选中的 assistant event；长 trace、steer 或 progress snapshot 场景不能让早期 assistant row 继续冒充最终摘要。 |
+| `finalAssistantTextTruncated` / `finalAssistantOutputTruncated` | 必须原样暴露被选中 assistant event 的截断标记；被选中的最终摘要截断时，消费侧应继续读 events 或 trace，而不是把截断隐藏成完整 final。 |
 | `failureKind` / `blocker` | 结构化失败分类和摘要；必须 redacted。 |
-| `lastSeq` / `eventCount` | 支持调用方增量轮询和 result/trace reconciliation。 |
+| `lastSeq` / `eventCount` / `eventsCapped` / `nextAfterSeq` | 支持调用方增量轮询和 result/trace reconciliation。result 聚合必须分页读取 events，不能只读取第一页后静默返回过期 `reply` 或 `lastSeq`；如果达到服务端聚合上限，必须 `eventsCapped=true` 并给出 continuation cursor。 |
+| `scopedLastSeq` / `scopedEventCount` | 指定 `commandId` 时暴露 command-scoped 聚合范围，方便上层区分 run 全局 cursor 和当前 command 事件范围。 |
 | `runId` / `commandId` / `attemptId` | 支持调用方持久关联和问题定位。 |
 | `artifactSummary` | 第一阶段只放有界摘要、字节数、截断标记和必要引用；不内嵌大 stdout/stderr。 |
 | `toolCallSummary` | 输出有界、脱敏的 tool call 状态摘要，至少包含 `count`、`statusCounts`、`exitCodeCounts` 和最近若干条 `items` 的 `method/toolName/type/status/exitCode/command`。消费侧必须用它区分 AgentRun command terminal、agent 内部工具执行和后置诊断，不得用单一 `hwpodExitCode` 覆盖 AgentRun 成功终态。 |
@@ -169,6 +172,8 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
 
 当 `commandId` 已指定，result envelope 必须只聚合该 command 的 assistant/output/error/terminal 事件；同一 run 的其他 command reply 不能串入当前 command result。未指定 `commandId` 时可默认选择最新 command。
 
+长 trace / steer 场景的验收标准是：raw events 已有 terminal seq 时，`commands result` 的 `lastSeq` 与 `eventCount` 必须覆盖同一终态事件范围，`finalAssistantSeq` 必须指向 terminal 前最后一条可用 assistant 或 authoritative final，且 silent first-page truncation 一律视为 result 合同失败。
+
 ## 测试规格
 
 ### T1 Manager health/readiness