docs: close out runner retention repair

docs/reference/agentrun.md

@@ -69,7 +69,6 @@ bun scripts/cli.ts agentrun control-plane status
 bun scripts/cli.ts platform-infra pipelines-as-code status --target NC01 --consumer agentrun-nc01-v02
 bun scripts/cli.ts platform-infra pipelines-as-code history --target NC01 --consumer agentrun-nc01-v02 --limit 10
 bun scripts/cli.ts agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --dry-run
-bun scripts/cli.ts agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --confirm
 bun scripts/cli.ts agentrun control-plane cleanup-runs --min-age-minutes 30 --limit 200 --dry-run
 bun scripts/cli.ts agentrun control-plane cleanup-runs --min-age-minutes 30 --limit 200 --confirm
 bun scripts/cli.ts agentrun control-plane cleanup-released-pvs --limit 200 --dry-run
@@ -155,7 +154,13 @@ HWLAB 通过 NC01 `agentrun-v02` 使用 Codex profile 时，`config.toml` 应只
 
 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`。该入口只做有界分类，不拥有删除 authority；必须由 AgentRun manager 在创建新 runner 前通过 DB fence 与 Kubernetes CAS 原子回收，UniDesk 不提供强杀参数，也不得为了验证 Kafka raw frame 直接裸删 Kubernetes Job/Pod。
+- runner 容量异常或 dispatch 被 retention 挡住时：
+  - 先运行 `agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --dry-run`；
+  - 该入口只读展示容量、候选和保护分类；
+  - 回收由既有 AgentRun manager 周期 reconciler 与 pre-create retention 自动完成；
+  - 空闲运行面应收敛到 `runnerJobCount=0`、`protectedActiveRunnerCount=0`；
+  - 终态命令仍被历史 claim、heartbeat、Pod 或 `runner-dispatch-retry` 保护时，修正 retention 分类；
+  - 禁止强杀 Job/Pod 或手工补 CI/CD。
 
 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。
 
@@ -175,8 +180,11 @@ AgentRun resource/session client policy 也由 `config/agentrun.yaml` 声明。`
   - `degradedReason`；
 - manager facts 或 Warning Event 查询不完整时返回 observation degraded；
 - `runnerJobCount === maxRunners` 时返回 at-capacity degraded，不能在下一次创建已经依赖尚未验收的 manager retention 时继续显示健康；
-- UniDesk 的 `--confirm` 固定 fail-closed，不按名称删除 Job/Pod；
-- 真正回收只能由 AgentRun manager 在 incoming runner 创建前通过 DB fence 与 Kubernetes CAS 原子完成；
+- UniDesk 不提供 runner 强杀入口，也不按名称删除 Job/Pod；
+- AgentRun manager 的周期 reconciler 必须分批回收所有明确 inactive 的 terminal、idle 和 stale-pending runner；
+- run/command 终态优先于历史 claim、heartbeat 和 Pod 活性观察；
+- `runner-dispatch-retry` 属于 manager 基础设施阶段，不能作为业务进展永久保护 pending runner；
+- stale-pending 保护窗口基于对象创建时间，持续 FailedMount Warning 不得刷新窗口；
 - manager facts 不可用时继续保护，不能把 Kubernetes 创建时间冒充为完整最后活跃事实。
 
 `cleanup-runs` 是 AgentRun `v0.2` 完成态 CI workspace retention 入口，只清理 `agentrun-ci` namespace 中超过 `--min-age-minutes` 的 `agentrun-v02-ci-*` PipelineRun，通过 Tekton ownerRef 释放临时 workspace PVC。dry-run 必须披露候选 PipelineRun、owned PVC、active mount 保护、local-path 实际估算 bytes 和 confirm 命令。默认保护最新完成的 PipelineRun，保留当前 CI/CD 状态证据。`cleanup-released-pvs` 是二次回收入口，只处理 `agentrun-ci`、`local-path`、`Delete` reclaim policy 的 `Released` PV；它不触碰 AgentRun runtime namespace、业务 PVC、Secret、registry storage 或 GitOps desired state。磁盘治理规则见 `docs/reference/gc.md`。