docs: record AgentRun Kafka event stream closeout

docs/reference/agentrun.md

@@ -111,8 +111,14 @@ Provider credential Secret 的 `auth.json` 和 `config.toml` 也必须按 NC01 l
 
 AgentRun runtime provider profile 的标准在线配置入口是 `bun scripts/cli.ts agentrun provider-profile plan|status|apply|validate --node NC01 --lane nc01-v02 --profile <profile>`。`plan/status` 必须输出 YAML 声明的 profile、backendProfile、SecretRef/key、fingerprint、runner egress/NO_PROXY 和 `valuesPrinted=false`；`apply --confirm` 只同步选中 profile 的 Secret/config、复用当前 manager image 渲染 GitOps、刷新 Argo 并重启 manager，不触发 image rebuild 或 PipelineRun；`validate` 只能作为配置和运行面可见性预检，不能替代 HWLAB Web/CLI 原入口真实 turn。需要确认某个 profile 已上线时，先跑 `provider-profile status` 看 live Secret fingerprint 和 manager env，再用 HWLAB Web dispatcher 等价入口创建新 session 并发送一轮真实 prompt。Web 入口验证优先使用 `web-probe observe start` + `observe command --type newSession` + `observe command --type sendPrompt --provider <profile>`，证据应包含 providerSelection、`/v1/agent/chat` 202、traceId、terminal turn 和 Final Response。
 
+仅修改 UniDesk YAML 中的 manager env、Kafka 开关、runner egress 或 provider config 时，不一定需要重建 AgentRun image。若 AgentRun source commit 已经是目标版本，应优先使用 `agentrun provider-profile apply --node NC01 --lane nc01-v02 --profile <declared-profile> --confirm` 复用当前 image 发布最新 YAML-rendered GitOps、刷新 Argo 并 rollout manager，再用窄查询确认 Deployment env 和新建 runner Job env；不要只看 `control-plane status` 的 manager source commit 对齐就认定 YAML env 已进入 runtime。
+
 HWLAB 通过 NC01 `agentrun-v02` 使用 Codex profile 时，`config.toml` 应只携带该 lane 需要的 Codex CLI runtime options，例如 model、reasoning、context window、auto compact、storage 和 network 相关键；除非对应 `auth.json` / API key source 也由同一 lane 明确拥有并已验证，否则不要在 lane config 中覆盖 provider endpoint、`base_url`、`model_provider` 或其他 endpoint 绑定。常见回归有两类：同步到 runner 的 config 缺少 `model_context_window` / `model_auto_compact_token_limit`，导致多轮 tool/webSearch 后报 context-window failure；或者为了补参数误加不匹配的 provider endpoint，导致 provider auth failure。修复必须走 `agentrun provider-profile apply --node NC01 --lane nc01-v02 --profile <profile> --confirm` 或对应 `control-plane secret-sync/restart`，并通过 HWLAB Web/CLI 原入口验证；不要从 Kubernetes Secret 反解配置内容或在 issue/trace 中打印 payload。
 
+AgentRun Kafka closeout 需要同时验证 manager 和 runner 两条生产链路。manager 侧至少创建一个短 run，并在 manager pod 内执行 `./scripts/agentrun kafka tail agentrun --run-id <runId>` 查到 `agentrun.event.v1` 的 `agentrun.run.created` 或后续 durable event；runner 侧必须创建真实 runner Job，并确认 Job env 中存在 `AGENTRUN_KAFKA_ENABLED`、`AGENTRUN_KAFKA_BOOTSTRAP_SERVERS`、`AGENTRUN_KAFKA_STDIO_TOPIC`、`AGENTRUN_KAFKA_STDIO_CLIENT_ID` 和 `AGENTRUN_KAFKA_STDIO_PRODUCE_ENABLED`，再用 `./scripts/agentrun kafka tail stdio --run-id <runId>` 查到 `codex-stdio.raw.v1` 的 stdin/stdout/stderr frame。默认查询不得展开 raw value；需要排查裸帧时才显式加 `--values`，并避免把 Secret value 写入 issue 或日志。
+
+如果 smoke runner 被 retention 挡住，先运行 `agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --dry-run`。只有 operator 明确接受中断旧 active runner 的风险时，才可按同参 `--force-active --dry-run` 确认 selected runner，再 `--force-active --confirm` 清理；不得为了验证 Kafka raw frame 直接裸删 Kubernetes Job/Pod。
+
 AgentRun resource/session client policy 也由 `config/agentrun.yaml` 声明。`client.sessionPolicy` 是未显式选择 node/lane 时 `agentrun send session/...` 和相关 session payload 生成的默认 `tenantId`、`projectId`、`providerId`、`backendProfile`、`workspaceRef` 和 execution policy 来源；显式 `--node <node> --lane <lane>` 后，`explain session-policy`、`send session`、resource primitives 和 AipodSpec render 都必须改用目标 lane 的 YAML 事实。lane `secrets[].providerCredential.profile` 声明 provider credential Secret 归属，UniDesk CLI 只按 YAML 聚合 Secret name/key，不再用代码拼接 provider Secret 名称。只读入口 `bun scripts/cli.ts agentrun explain session-policy` 用于查看选中目标 lane、policy 来源、实际 executionPolicy payload 和 provider credential binding 来源；输出只能包含 Secret metadata、key 名和 `valuesPrinted=false`，不得打印 Secret value。
 
 非默认 lane 的 session follow-up 必须证明 `send session` 使用的是选中 node/lane 的 run policy。使用短命令形态前，先用 `agentrun explain session-policy --node <node> --lane <lane> [--backend-profile <profile>]` 或等价 dry-run/describe 路径确认 `backendProfile`、`providerId`、`workspaceRef`、execution policy 和 provider credential SecretRef 都来自目标 lane；`--prompt-stdin` 短命令形态和 `--json-stdin -o json` 显式 JSON 形态应披露同一份 `sessionPolicy` 摘要。渲染结果回退到全局默认 lane、显示错误的 default lane，或短命令与 JSON body 使用不同 policy，都是 lane policy 缺陷，应修复 YAML 目标解析或 CLI 渲染；不得通过手工创建默认 lane Secret、复制凭据、改写 JSON body 或修改 runtime namespace 来掩盖 policy 选错的问题。