docs: 固化 CaseRun agent compile-only 决策

docs/reference/agentrun-code-agent-dispatch.md

@@ -8,6 +8,7 @@
 - `createHwlabAgentRunDispatchAssembly()` 生成 AgentRun `POST /api/v1/runs`、`POST /api/v1/runs/:runId/commands` 和 `POST /api/v1/runs/:runId/runner-jobs` 三段 payload。
 - `dispatchHwlabAgentRun()` 使用同一 assembly 顺序调用 AgentRun manager；调用方可以注入 `fetchImpl` 做合同测试或接入真实 manager。
 - 默认 manager URL 是 `http://agentrun-mgr.agentrun-v01.svc.cluster.local:8080`，默认 namespace 是 `agentrun-v01`，默认 providerId 是 `G14`，默认 workspace branch 是 `v0.2`。
+- 人工和 agent 触发 HWLAB Code Agent 任务时，优先使用已成型的 `hwlab-cli client agent session create/send/result/trace`、Workbench 同路径 API 或 CaseRun 封装入口；只有在修 adapter/dispatcher/合同测试时才手写 AgentRun payload。排查 provider、API key、session 或 trace 问题时，先用这些 CLI 原入口确认 runtime config、SecretRef、session、trace 和 result，再定位具体组件，不把问题绕成 generic provider API、runner shell、直连 Cloud API 或临时脚本路径。
 
 ## 会话和执行边界
 

docs/reference/spec-hwpod-harness.md

@@ -205,6 +205,8 @@ CaseRun 的 case registry repo 与 subject repo 必须分离。标准 registry r
 
 agent-task CaseRun 的 evidence 必须至少记录：subject repo 本地路径、subject commit、隔离 worktree、任务 prompt 来源、Code Agent session/trace/provider/model、agent 产生的 workspace diff、验证动作和验证结果。compile-only smoke 的 evidence 不得伪造或补写 agent provenance。
 
+Agent compile-only 阶段必须走 HWLAB Code Agent / AgentRun 的成熟入口：CaseRun 负责生成 prompt/context、创建或调用显式 Code Agent session，并通过 `case run start/status/result/logs` 轮询终态；prompt 必须要求 agent 在自己的 AgentRun workspace 内使用标准 `hwpod` / `hwpod-ctl` 执行 compile-only 验证，例如 `hwpod-ctl spec validate`、`hwpod inspect` 和 `hwpod build`。CaseRun 可以保留 runner 后置 compile 作为收尾或对照证据，但 evidence 必须把 agent trace 中的 HWPOD commandExecution 与 runner 后置 `hwpod-cli build` 分开记录，不得把 runner 直接编译伪装成 agent 编译。
+
 CaseRun 是强化学习 Harness 的最小执行单元，但它本身不是完整 epoch。完整 epoch 还需要样本选择、策略生成、奖励/评价、批量调度、跨 run 归因和自动训练闭环；第一阶段只要求一个 `caseId` 能从 case registry repo 进入真实 HWPOD 编译闭环，并把可审计产物稳定落盘。
 
 最小入口：
@@ -220,7 +222,7 @@ bun tools/hwlab-cli/bin/hwlab-cli.ts case run result <runId>
 bun tools/hwlab-cli/bin/hwlab-cli.ts case run logs <runId> --tail 8000
 ```
 
-`case run` 在当前版本只负责编排流程和记录原始证据，不做 evidence 自动评价、自动打分或门禁判断。流程是：prepare 先在 subject repo 本地 checkout 下创建 `.worktree/caserun-<runId>` 隔离 worktree并写入 run-local spec，然后生成 Code Agent prompt/context，创建或调用 HWLAB Code Agent session，把 isolated worktree、run-local HWPOD spec、任务目标和约束交给 Code Agent；agent 阶段结束或超时后，CaseRun 采集 subject worktree 的 `git status` / `git diff --stat` / `git diff --binary`，再调用 `hwpod-cli build`，通过 `cmd.run` 查询 Keil 异步 job-status，最后收集 `evidence.json` 到 run state，并把审计副本写入 case registry repo 的 `runs/<caseId>/<runId>/`。下载不作为 compile-only CaseRun 的隐式步骤；后续需要下载时，应作为独立 action 显式加入 case 定义和流程记录。
+`case run` 在当前版本只负责编排流程和记录原始证据，不做 evidence 自动评价、自动打分或门禁判断。流程是：prepare 先在 subject repo 本地 checkout 下创建 `.worktree/caserun-<runId>` 隔离 worktree并写入 run-local spec，然后生成 Code Agent prompt/context，创建或调用 HWLAB Code Agent session，把 isolated worktree、run-local HWPOD spec、任务目标和约束交给 Code Agent；agent 阶段结束或超时后，CaseRun 采集 agent trace/terminal state/commandExecution 摘要、subject worktree 的 `git status` / `git diff --stat` / `git diff --binary`，再按 case 定义执行 runner 后置 `hwpod-cli build` 和 `cmd.run` Keil 异步 job-status 查询，最后收集 `evidence.json` 到 run state，并把审计副本写入 case registry repo 的 `runs/<caseId>/<runId>/`。下载不作为 compile-only CaseRun 的隐式步骤；后续需要下载时，应作为独立 action 显式加入 case 定义和流程记录。
 
 长时间 CaseRun 必须优先使用 `case run start/status/result/logs` 短连接形态，而不是用 shell/nohup 包装同步 `case run`。`start` 只负责创建 `.state/hwlab-cli/caserun/<runId>/`、启动后台 worker 并立即返回 `runId`、PID、stdout/stderr 路径和下一条查询命令；`status`、`result`、`logs` 都是短查询。`run.json` 是阶段状态权威，阶段开始时就要刷新 `status`、`stage`、`traceId/sessionId/conversationId/threadId`、AgentRun/trace 轮询信息、stdout/stderr byte count 和下一条轮询命令；长等待期间不得出现无输出、无 trace、无状态文件更新的黑洞窗口。