From 3ea06cabdb92ff5be50562563fda1b2dfa5dc886 Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 12 Jul 2026 19:05:26 +0200 Subject: [PATCH] docs: close out runner retention repair --- .../skills/unidesk-cicd/references/agentrun.md | 12 ++++++------ docs/MDTODO/agentrun-runtime-reliability.md | 4 ++-- .../R4.4_Task_Report.md | 7 +++++++ docs/reference/agentrun.md | 16 ++++++++++++---- 4 files changed, 27 insertions(+), 12 deletions(-) create mode 100644 docs/MDTODO/details/agentrun-runtime-reliability/R4.4_Task_Report.md diff --git a/.agents/skills/unidesk-cicd/references/agentrun.md b/.agents/skills/unidesk-cicd/references/agentrun.md index 11a2d9c5..4e5807a7 100644 --- a/.agents/skills/unidesk-cicd/references/agentrun.md +++ b/.agents/skills/unidesk-cicd/references/agentrun.md @@ -12,7 +12,7 @@ bun scripts/cli.ts agentrun control-plane apply --node D601 --lane v02 [--dry-ru bun scripts/cli.ts agentrun control-plane secret-sync --node D601 --lane v02 [--dry-run|--confirm] bun scripts/cli.ts agentrun control-plane restart --node D601 --lane v02 [--dry-run|--confirm] bun scripts/cli.ts agentrun control-plane trigger-current --node D601 --lane v02 [--dry-run|--confirm] -bun scripts/cli.ts agentrun control-plane cleanup-runners --node D601 --lane v02 [--dry-run|--confirm] +bun scripts/cli.ts agentrun control-plane cleanup-runners --node D601 --lane v02 --dry-run bun scripts/cli.ts agentrun describe runnerjob/ --run --node D601 --lane v02 -o json bun scripts/cli.ts agentrun control-plane status --node D601 --lane v02 [--pipeline-run |--source-commit ] [--full|--raw] bun scripts/cli.ts platform-infra gitea mirror status --target JD01 [--full|--raw] @@ -29,11 +29,11 @@ bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01 [--full - 默认有界显示 observation、capacity、最近活跃、heartbeat、业务进展、Pod waiting reason 和 `stale-pending`； - capacity 摘要必须显示 `/`、`status`、`availableSlots`、typed blocker 和 `degradedReason`； - `runnerJobCount === maxRunners` 时必须返回 at-capacity degraded，不能在下一 runner 已依赖 manager retention 时继续报告健康； - - `--confirm` 在 UniDesk 侧固定 fail-closed，不按旧 Job 名称删除； - - 真正删除由 AgentRun manager 的 DB fence 和 Kubernetes CAS 原子入口负责： - - 分类与 pre-create retention 跟踪 [AgentRun #280](https://github.com/pikasTech/agentrun/issues/280)； - - 原子实现跟踪 [PR #281](https://github.com/pikasTech/agentrun/pull/281)； - - 无 incoming create 时的批量陈旧对象终态化和回收由同一 manager authority 的 [AgentRun #282](https://github.com/pikasTech/agentrun/issues/282) 跟踪。 + - UniDesk 不提供 runner 强杀入口，也不按名称删除 Job/Pod； + - AgentRun manager 的既有周期 reconciler 与 pre-create retention 负责自动分批回收； + - 终态事实必须优先于历史 claim、heartbeat 和 Pod 活性观察； + - `runner-dispatch-retry` 不属于业务进展，不能永久保护 pending runner； + - 空闲运行面的验收值是 `runnerJobCount=0`、`protectedActiveRunnerCount=0`。 - `describe runnerjob/`: - 先通过 manager 精确读取 runner job identity； - 再按精确 Job name、`job-name` Pod label 和 Pod name Warning Event 查询运行面； diff --git a/docs/MDTODO/agentrun-runtime-reliability.md b/docs/MDTODO/agentrun-runtime-reliability.md index ff7bf0bc..875a0031 100644 --- a/docs/MDTODO/agentrun-runtime-reliability.md +++ b/docs/MDTODO/agentrun-runtime-reliability.md @@ -71,9 +71,9 @@ ### R4.3 解决 [AgentRun #330](https://github.com/pikasTech/agentrun/issues/330)：修复 manager 已选定 inactive runner 后删除其关联 Secret 失败导致 dispatch 无法释放容量；只处理对象归属、NotFound 幂等和 typed failure，禁止扩展合同、租约、安全机制、围栏或容量架构，自动上线后以原 task qt_fd1c18a8bb04490d8bbb838885d1f436 成功 dispatch 验收，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R4.3_Task_Report.md)。 -### R4.4 +### R4.4 [completed] -解决 [AgentRun #332](https://github.com/pikasTech/agentrun/issues/332)：终态 run/command 不得被历史 claim、registration、heartbeat 或 stale-pending 窗口判为 protectedActive；最小调整 retention 分类优先级并补定向测试，不新增/扩展合同、租约、安全机制、围栏、CAS 或容量架构，自动上线后空闲 runner 容量应接近 0。，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R4.4_Task_Report.md)。 +解决 [AgentRun #332](https://github.com/pikasTech/agentrun/issues/332)：修正终态 runner 与 manager 基础设施事件的假活分类，让既有周期 reconciler 自动回收所有 inactive runner；不新增合同、租约、安全机制、围栏、CAS 或容量架构，以 NC01 空闲容量收敛到 0/20 验收，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R4.4_Task_Report.md)。 ## R5 [in_progress] 完善 Artificer AipodSpec、primary workspace、resource bundle 物化与业务 turn admission，使声明式源码快照、能力 bundle 和失败可见性形成单一合同，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5_Task_Report.md)。 diff --git a/docs/MDTODO/details/agentrun-runtime-reliability/R4.4_Task_Report.md b/docs/MDTODO/details/agentrun-runtime-reliability/R4.4_Task_Report.md new file mode 100644 index 00000000..476b6c96 --- /dev/null +++ b/docs/MDTODO/details/agentrun-runtime-reliability/R4.4_Task_Report.md @@ -0,0 +1,7 @@ +# R4.4 任务报告 + +- 根因一：终态 run/command 的事实晚于历史 claim、heartbeat 和 Pod 活性判定，导致 completed runner 被错误保护。 +- 根因二：`runner-dispatch-retry` 被误认作业务进展，导致旧 pending runner 永久保护。 +- 修复：AgentRun PR #333 调整终态分类优先级并让既有周期 reconciler 分批回收全部 inactive candidate；PR #334 修正 dispatch retry 的事件分类。 +- 验证：两个 PR 均经 GitHub webhook、Gitea mirror、PaC、Tekton、GitOps 和 Argo 自动上线；未人工触发 CI/CD，未强杀 runner。 +- 运行面：`cleanup-runners --dry-run` 最终显示 `runnerJobCount=0`、`protectedActiveRunnerCount=0`、`usage=0/20`。 diff --git a/docs/reference/agentrun.md b/docs/reference/agentrun.md index a378bc5f..00388d99 100644 --- a/docs/reference/agentrun.md +++ b/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 ` 查到 `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 ` 查到 `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 --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`。