fix: clarify caserun hwpod job polling

docs/reference/spec-hwpod-harness.md

@@ -211,7 +211,7 @@ bun tools/hwpod-cli.ts job status <jobId> --spec .hwlab/hwpod-spec.yaml
 bun tools/hwpod-cli.ts uart read --spec .hwlab/hwpod-spec.yaml --port uart1 --max-bytes 4096
 ```
 
-直调入口只用于单步定位和原链路复测：`build` / `download` 返回 Keil async job accepted 只能证明命令已投递，不能等同于编译或下载成功；必须继续用 `hwpod-cli job status <jobId>` 轮询终态，并结合 `uart read`、Keil result 或目标串口日志解释结果。串口被人工工具占用时，应先释放 COM 口或读取已有 serial-monitor 数据解释现象，不得把 COM 口占用误判成 DAPLink、目标板或 API 不可用。
+直调入口只用于单步定位和原链路复测：`build` / `download` 返回 Keil async job accepted 只能证明命令已投递，不能等同于编译或下载成功；必须继续用独立短命令 `hwpod-cli job status <jobId>` 轮询终态，不要把轮询包进 `sleep &&`、`timeout`、`watch`、`head`、pipe 或 shell loop。解释结果时结合 `uart read`、Keil result 或目标串口日志。串口被人工工具占用时，应先释放 COM 口或读取已有 serial-monitor 数据解释现象，不得把 COM 口占用误判成 DAPLink、目标板或 API 不可用。
 
 ### CaseRun 让 code agent 调 hwpod-cli
 
@@ -230,6 +230,8 @@ hwpod job status <jobId> --spec .hwlab/hwpod-spec.yaml
 hwpod uart read --spec .hwlab/hwpod-spec.yaml --port uart1 --max-bytes 4096
 ```
 
+对 Code Agent 而言，Keil/HWPOD 长任务同样遵循 cli-spec 短连接组合：`build` 或 `download` 只负责返回 async job id，`job status` 必须作为独立短命令少量轮询；若仍处于 running，应报告 job id、status、diagnostics 和当前判断，不要用长 shell 等待把 agent 子阶段拖成黑盒。
+
 CaseRun prompt 只能描述任务、边界、允许修改的文件、必须尝试的 HWPOD 命令和需要回报的 raw output/job id/串口尾部；不得把具体源码补丁、预期答案或自动评价逻辑写成 prompt。CaseRun result 负责归档 agent session id、trace id、agent message、final response、workspace diff、HWPOD command trace 和 registry run 产物；不做 evidence 自动评价、不做门禁、不把 runner 后置命令伪装成 agent 命令。若某个步骤卡住，先用人工单步直调入口复测同一 spec 和同一 subject worktree，确认是 HWPOD CLI/Keil/serial-monitor/hwpod-node 业务问题后再修复对应组合层或 node 本体。
 
 ## CaseRun 无服务阶段

skills/hwpod-cli/SKILL.md

@@ -24,7 +24,7 @@ The HWPOD spec is code-agent-side state. The default path is `.hwlab/hwpod-spec.
 - Inspect the HWPOD path: `hwpod inspect --spec .hwlab/hwpod-spec.yaml`.
 - Workspace read/edit: use `hwpod workspace ls|cat|read|write|replace|insert-after|apply-patch --spec .hwlab/hwpod-spec.yaml`. `read` is an alias for `cat`; `--file` and `--remote-path` are accepted as path aliases.
 - Build/download/reset: use `hwpod build`, `hwpod download`, and `hwpod reset`; the compiler must translate these through existing file ops and `cmd.run` where possible.
-- Keil async status: after build/download returns a job id, use `hwpod job status <jobId> --spec .hwlab/hwpod-spec.yaml` instead of shell polling wrappers.
+- Keil async status: after build/download returns a job id, use separate short `hwpod job status <jobId> --spec .hwlab/hwpod-spec.yaml` calls instead of shell polling wrappers such as `sleep &&`, `timeout`, `watch`, `head`, pipes, or loops.
 - UART read: use `hwpod uart read --spec .hwlab/hwpod-spec.yaml --port uart1`; the compiler runs the configured serial-monitor CLI through `cmd.run`.
 - For early debug bindings, put command bindings in `.hwlab/hwpod-spec.yaml` with `spec.workspace.buildCommand`, `spec.debugProbe.downloadCommand`, or `spec.debugProbe.resetCommand`.
 

tools/hwlab-cli/caserun.test.ts

@@ -465,7 +465,8 @@ test("case run orchestrates agent prompt, diff capture, and compile evidence wit
     assert.match(prompt, /hwpod-ctl spec validate --spec \.hwlab\/hwpod-spec\.yaml/u);
     assert.match(prompt, /standard hwpod\/hwpod-ctl commands/u);
     assert.match(prompt, /hwpod job status <jobId> --spec \.hwlab\/hwpod-spec\.yaml/u);
-    assert.match(prompt, /不要再用 shell timeout\/head\/pipe 包住/u);
+    assert.match(prompt, /不要再用 shell sleep\/&&\/timeout\/watch\/head\/pipe/u);
+    assert.match(prompt, /separate short `hwpod job status <jobId> --spec \.hwlab\/hwpod-spec\.yaml` commands/u);
     const diff = await readFile(path.join(cwd, ".state", "hwlab-cli", "caserun", "run-agent-flow", "agent-diff.patch"), "utf8");
     assert.match(diff, /printf\("hello"\)/u);
     assert.equal(requests.some((item) => item.url === "http://web.test/v1/agent/sessions"), true);

tools/src/hwlab-caserun-lib.ts

@@ -1043,7 +1043,7 @@ async function renderAgentTaskPrompt(run: PreparedCaseRun, agentTask: PreparedAg
     "如果 .hwlab/hwpod-spec.yaml 缺失或内容明显不是本次 case，请报告 CaseRun workspace setup 错误，不要自行编造或迁移 spec。",
     "若 case prompt 要求源码修改，必须只改 subjectWorktreePath；若 prompt 未要求源码修改，则保持 subject 源码不变。",
     "不要运行 CaseRun 答案执行器；你本人必须通过 hwpod/hwpod-ctl 标准入口触发编译验证。",
-    "hwpod build/download 是长任务短连接入口；不要再用 shell timeout/head/pipe 包住它们。记录返回 JSON 里的 jobId/job_id，再用 hwpod job status <jobId> --spec .hwlab/hwpod-spec.yaml 做有限轮询。"
+    "hwpod build/download 是长任务短连接入口；不要再用 shell sleep/&&/timeout/watch/head/pipe 或 shell loop 包住它们。记录返回 JSON 里的 jobId/job_id，再用独立的 hwpod job status <jobId> --spec .hwlab/hwpod-spec.yaml 短命令做有限轮询。"
   ].filter(Boolean);
   return [
     `# HWPOD CaseRun Code Agent Task`,
@@ -1070,7 +1070,7 @@ async function renderAgentTaskPrompt(run: PreparedCaseRun, agentTask: PreparedAg
     `- Run \`hwpod-ctl spec validate --spec .hwlab/hwpod-spec.yaml\`.`,
     `- Run \`hwpod inspect --spec .hwlab/hwpod-spec.yaml\`.`,
     `- Follow the case task using standard hwpod/hwpod-ctl commands. Run build/download/UART steps only when the case explicitly asks for them, and report returned JSON/job/artifact/serial summaries.`,
-    `- For hwpod build/download, keep the HWPOD command unwrapped so it can return async JSON; then poll the returned job id with \`hwpod job status <jobId> --spec .hwlab/hwpod-spec.yaml\` a bounded number of times.`,
+    `- For hwpod build/download, keep the HWPOD command unwrapped so it can return async JSON; then poll the returned job id with separate short \`hwpod job status <jobId> --spec .hwlab/hwpod-spec.yaml\` commands a bounded number of times. Do not wrap status polling with shell sleep, &&, timeout, watch, head, pipes, or shell loops.`,
     `- CaseRun will inspect git diff under subjectWorktreePath after your turn completes and may run a runner post-check compile as separate evidence.`,
     `- CaseRun records trace/session/conversation, agent commandExecution, workspace diff and Keil build evidence without auto-grading them.`
   ].join("\n");