fix: 收敛 device-pod DS 验收 CLI 摩擦

docs/reference/spec-device-pod.md

@@ -386,6 +386,26 @@ bun tools/device-pod-cli.ts D601-F103-V2:debug-probe download start \
 
 Code-agent/DS runner 内执行同类验收时，把 `bun tools/device-pod-cli.ts` 换成 `hwpod`；只有 `hwpod` 不在 PATH 时才临时 fallback 到 `/app/skills/device-pod-cli/scripts/device-pod-cli.mjs`。UART 串口若被 Windows 侧工具占用，应把 COM busy/access denied 记录为可选串口证据缺口，Keil build/download 是否通过以 job output 中的 build summary、`Programming Done`、`Verify OK` 和 `Application running` 为准。
 
+DS 或其他 code-agent runner 由 `hwlab-cli client harness submit` 触发时，控制面应保持短连接：提交后用 `client harness result`、`client harness trace --limit <N>` 和 `client harness audit --require-bootsharp` 轮询，不把 UniDesk `ssh/tran` 连接长期挂在一次 `wait` 上。`client harness wait` 只用于短窗口观察，CLI 会把超长等待压到低于 UniDesk 透传硬超时的安全窗口，并在 JSON 中返回后续短轮询命令。
+
+job 观察优先使用 cloud-api job 入口，避免从 shell 管道里解析整段 JSON：
+
+```bash
+hwpod job status --pod-id D601-F103-V2 <jobId> --api-base-url <url> --cookie "$COOKIE"
+hwpod job output --pod-id D601-F103-V2 <jobId> --api-base-url <url> --cookie "$COOKIE"
+```
+
+`build status/output/cancel <jobId>` 和 `download status/output/cancel <jobId>` 只作为 selector 便捷别名；当 `<jobId>` 是 `job_devicepod_*` 这类 cloud-api job 时，别名必须映射到 `/jobs/<jobId>` 或 `/jobs/<jobId>/output`，不得误启动新的 build/download job。Keil host 侧子 job 仍保留 `build status <hostJobId>` 或 `download status <hostJobId>` 语义，用于查看 Windows `device-host-cli` 创建的嵌套 job。
+
+搜索下载、烧录或串口证据时，带空格、管道符或较长正则的 `workspace rg` 应使用显式参数，避免本地 shell、selector 和 Windows host 三层参数解析产生歧义：
+
+```bash
+hwpod D601-F103-V2:workspace:/ rg \
+  --pattern "Programming Done|Verify OK|Application running|Error" \
+  --path projects/01_baseline/captures \
+  --api-base-url <url> --cookie "$COOKIE"
+```
+
 验收通过条件：`client device-pods status` 返回 `status=ok` 且 `blocker=null`；gateway sessions 中 `gws_D601_F103` 为 online；`device-pod-cli` job 进入 `completed`，且 D601 Windows gateway `/status.lastDispatch.operationId` 与该 job 的 `operationId` 一致并有 `lastResultAt`。旧 `gws_d601_win_71_freq` session 只能作为历史 stale 线索，不能作为 v0.2 F103 gateway 的目标命名。
 
 ## 测试规格