docs: record AgentRun codex stdio otel closeout

docs/reference/agentrun.md

@@ -171,6 +171,16 @@ HWLAB CaseRun 需要专用 skill 时，skill 必须通过 AgentRun `gitbundle` r
 
 HWLAB Code Agent provider profile 的 `config.toml`、完整 Codex `auth.json` 提交、Secret 证据和真实 profile 试机规则统一见 `docs/reference/hwlab.md#code-agent-provider-profile-配置与验收`。本 AgentRun 参考只维护 AgentRun 仓库、运行面、CI/CD 和跨仓库职责边界，不重复维护 HWLAB profile 凭证语义。
 
+## AgentRun / HWLAB OTel 追踪口径
+
+HWLAB Workbench、Code Agent 或 CaseRun 出现 turn 长时间无新活动、`waitingFor=code-agent`、`idle-after-tool`、provider stream 断开、工具调用后缺 terminal，或用户质疑 AgentRun/codex-stdio 仍在运行但 trace 没追穿时，必须用同一条 OTel trace 同时验证 HWLAB、AgentRun manager 和 AgentRun runner 三层。只看到 HWLAB business trace 或 manager dispatch span 不足以证明已经追到 codex app-server/codex-stdio。
+
+AgentRun runner-side instrumentation 必须从 manager 创建 runner Job 时传递 OTEL endpoint/service env 和稳定 `runnerJobId`，runner 启动后把 `runId`、`commandId`、`runnerJobId`、`runnerId`、`sessionId`、`threadId`、`turnId`、`backendProfile`、`sourceCommit`、`traceId` 与 `otel.trace_id` 写入关键 span。所有 span 与 JSONL 事件都必须保留 `valuesPrinted=false`，敏感配置、prompt、凭据、tool output 和 provider payload 只允许以长度、hash、fingerprint、status、exit code 或枚举原因披露。若声明 `AGENTRUN_LOG_PATH`，runner 必须创建该 JSONL 并写入有界、脱敏的 lifecycle label，不能只在环境变量里声明。
+
+codex app-server backend 的最小可追踪面包括 app-server lifecycle、thread、turn、tool、idle 和 provider stream 断开：`codex_app_server.starting`、`codex_app_server.started`、进程退出时的 `codex_app_server.exit`，以及 `codex_stdio.thread_start.*` / `codex_stdio.thread_resume.*`、`codex_stdio.turn_start.*`、`codex_stdio.tool_call.started|completed|failed`、`codex_stdio.turn_completed`、`codex_stdio.idle_warning`、`codex_stdio.idle_timeout`、`codex_stdio.provider_stream_disconnected` 和 `codex_stdio.missing_terminal_after_tool`。Codex notification 中 `item/started` 且 `status=inProgress`、`running` 或等价状态必须归一化为 `tool_call.started`，不得误报为 completed。
+
+收口验证必须走 HWLAB Web dispatcher 等价原入口或同一 dispatcher 的 CLI，触发一条新 turn 并尽量包含一次只读工具调用；然后用 `bun scripts/cli.ts platform-infra observability trace --target <node> --trace-id <otelTraceId> --grep codex_stdio --full` 查询 Tempo。通过证据应显示 `services` 至少覆盖 `hwlab-cloud-api`、`agentrun-manager` 和 `agentrun-runner`，codex span 中 `runId`、`commandId`、`runnerJobId` 不缺失，`valuesPrinted=false`，且错误 span 与业务终态一致。旧 trace 不会因后续 instrumentation 修复自动回填；旧 trace 缺少 codex runner span 时，只能写成“当时未采集到该事件”，不能倒推出 AgentRun 或 codex-stdio 当时没有运行。
+
 ## AgentRun / HWLAB 失败归因标准
 
 HWLAB 通过 AgentRun 执行 Code Agent turn 时，失败归因必须以 AgentRun backend adapter 的结构化 failure kind 为准。AgentRun 负责把 provider、thread、runner、bundle 和 command lifecycle 的失败分类成稳定语义；HWLAB 负责原样消费并映射到用户可读分类。不得为了让 UI 或 issue 收口看起来更顺，把 AgentRun/provider 错误改写成 device-pod、gateway、Cloud API endpoint 或前端渲染问题。