pikasTech-unidesk/docs/MDTODO/agentrun-runtime-reliability.md

# AgentRun 运行可靠性

来源：[AgentRun #294](https://github.com/pikasTech/agentrun/issues/294)。

范围：长期跟踪 AgentRun admission、dispatch、runner、resource bundle、provider 建立、终态失败可见性与自动交付可靠性。单次故障作为 MDTODO ITEM 纳入，不为每个 issue 新建文件。


## R1 [completed]

依据 [AgentRun #294](https://github.com/pikasTech/agentrun/issues/294) 恢复 Artificer resource-bundle Git 获取与失败可见性，完成任务后将详细报告写入[任务报告](./details/agentrun-resource-bundle-git-fetch/R1_Task_Report.md)。
### R1.1 [completed]

用固定四个 run 单步披露 bundle source、fetch 阶段、脱敏 remote/credential sourceRef 与首个失败分类，完成任务后将详细报告写入[任务报告](./details/agentrun-resource-bundle-git-fetch/R1.1_Task_Report.md)。
### R1.2 [completed]

在 YAML/sourceRef 或 AgentRun runner/resource-bundle 权威路径修复 code 128，并统一 task terminal failure 摘要，完成任务后将详细报告写入[任务报告](./details/agentrun-resource-bundle-git-fetch/R1.2_Task_Report.md)。
### R1.3 [completed]

通过 PR 合并自动 CI/CD 后重派同类 Artificer 任务，验收 bundle materialized、provider established 和业务执行开始，完成任务后将详细报告写入[任务报告](./details/agentrun-resource-bundle-git-fetch/R1.3_Task_Report.md)。

## R2 [completed]

在不改变产品事件、持久化、trace authority 或跨服务职责的前提下，清理 AgentRun/HWLAB 观测诊断 CLI 支线；来源 [UniDesk #1619](https://github.com/pikasTech/unidesk/issues/1619) 与 [UniDesk #1796](https://github.com/pikasTech/unidesk/issues/1796)，任何架构变更均跳过，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R2_Task_Report.md)。

### R2.1 [completed]

落实 [UniDesk #1619](https://github.com/pikasTech/unidesk/issues/1619)：仅在 CLI 输出层增加有界 plan 默认视图和 observability scoped help，显式 full/raw 保持完整；禁止提高 stdout 阈值、修改 YAML 或运行面，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R2.1_Task_Report.md)。

### R2.2 [completed]

落实 [UniDesk #1796](https://github.com/pikasTech/unidesk/issues/1796)：仅修既有诊断层的 lane 选择、commandId 过滤和 missing-command-terminal-span 的 unknown/instrumentation-gap 分类；禁止新增第二事实源或改变 trace authority，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R2.2_Task_Report.md)。

### R2.3 [completed]

由主代理完成架构 diff review、定向 CLI 验收、PR 合并与 issue 收口；只接受局部诊断/可见性修改，rollout 不适用，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R2.3_Task_Report.md)。

### R2.4 [completed]

登记 [UniDesk #1801](https://github.com/pikasTech/unidesk/issues/1801)：diagnose 的 command/result 读取会向同一业务 trace 补记 command_result span，使重复读取改变 instrumentation completeness；该问题涉及 trace context 与诊断证据隔离，本轮按架构变更边界跳过，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R2.4_Task_Report.md)。

## R3 [completed]

依据 [AgentRun #307](https://github.com/pikasTech/agentrun/issues/307) 实现 Queue Q5 的同 task 不可变 attempt 历史与显式终态失败 retry，禁止通过重置 task 或复制 task 合同绕过资源语义，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R3_Task_Report.md)。

### R3.1 [completed]

在 AgentRun 增加正式 `agentrun_queue_attempts` 存储、现有 latestAttempt 回填和不可变历史查询；task.latestAttempt 只保留为摘要指针，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R3.1_Task_Report.md)。

### R3.2 [completed]

实现服务端 `POST /api/v1/queue/tasks/:id/retry`：同 task 新 attempt、retry key 幂等、failed/blocked 白名单、completed/cancelled fail closed，并让 dry-run 全校验且零写入，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R3.2_Task_Report.md)。

### R3.3 [completed]

在 UniDesk 受控 CLI 增加 task retry 资源入口，完成内存/PostgreSQL 并发测试、PR 自动交付和固定任务 `qt_5b65a086385a49bdb874cf8f9d191169` 的 bundle/provider/业务启动验收，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R3.3_Task_Report.md)。

## R4 [in_progress]

完善 AgentRun runner 生命周期、claim 释放、容量门禁与 manager 权威回收，使终态一致性、并发安全和有界诊断形成单一可靠合同，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R4_Task_Report.md)。

### R4.1 [in_progress]

解决 [AgentRun #309](https://github.com/pikasTech/agentrun/issues/309)：终态 run/command 与终态 Pod 不得因陈旧 runClaimedBy 被判假活并占满 maxRunners；对齐 [AgentRun #280](https://github.com/pikasTech/agentrun/issues/280) 的 retention 边界，由 manager 原子释放 claim、终态化和 CAS 回收，完成并发测试、自动交付及 NC01 受控 CLI 验收，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R4.1_Task_Report.md)。

#### R4.1.1 [in_progress]

解决 [UniDesk #1820](https://github.com/pikasTech/unidesk/issues/1820)：对齐 cleanup-runners 只读 observer 与 AgentRun manager retention 的终态 claim 分类，默认有界披露 terminal-run-stale-claim、repairKind 和一致的 candidate/protected 计数；manager 保持唯一回收 authority，禁止增加删除入口或第二事实源，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R4.1.1_Task_Report.md)。
## R5 [in_progress]

完善 Artificer AipodSpec、primary workspace、resource bundle 物化与业务 turn admission，使声明式源码快照、能力 bundle 和失败可见性形成单一合同，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5_Task_Report.md)。

### R5.1 [in_progress]

解决 [AgentRun #310](https://github.com/pikasTech/agentrun/issues/310)：Artificer 已报告 resource-bundle-materialized 却未物化 primary UniDesk workspace；禁止 agent 自行 clone、借用宿主 worktree 或 trans 源码旁路。旧 task 已错误进入不可变 completed，修复自动交付后须以相同 cadence 与哨兵报告业务目标创建新的 Artificer task，并以 Artificer 自身完成作为验收，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.1_Task_Report.md)。

#### R5.1.1 [in_progress]

审核并修复 [AgentRun PR #312](https://github.com/pikasTech/agentrun/pull/312) 后续暴露的 session workspace 连续性与源码清洁性：真实 Artificer run `run_d2cd5c7b9c4149a28dd6e8403c77fa01` 已在 seq=8 精确物化 UniDesk master `d3f6d1cd335b` 到 primary workspace `.`，但 seq=35 因受管 capability bundle 覆盖产生 `.agents/skills/*` 与 `tools/` untracked 而错误判定源码已脏并 fail closed；修复必须让受管覆盖不污染 Git source view、不得隐藏真实源码改动，并保持同 session 后续 run/runner 的 source/workspace identity 与安全恢复。PR merge 后只允许自动交付，再用两项固定 Artificer 业务目标验收；禁止主代理代做、agent clone、宿主 worktree、trans 源码旁路或人工 CI/CD，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.1.1_Task_Report.md)。

### R5.2 [completed]

解决 [AgentRun #313](https://github.com/pikasTech/agentrun/issues/313)：真实 Artificer task `qt_5cbeb5c338974d14b4d55336a412fc00` 的 AipodSpec 摘要声明 github-ssh SecretRef，但 task input 的 `executionPolicy.toolCredentials` 仅保留 github-pr 与 unidesk-ssh，证明 volume credential 在 create/render/admission 阶段已丢失，既有 runner 子进程继承修复无法生效；补齐声明到 task、runner mount、backend commandExecution 的完整投影，使真实 git SSH push 可用。缺 key、known_hosts 或环境继承时必须脱敏 typed fail closed；禁止 `/root/.ssh`、ssh-keyscan、token URL、匿名 transport、人工 CI/CD 或主代理代做业务任务，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.2_Task_Report.md)。

### R5.3 [in_progress]

解决 [AgentRun #219](https://github.com/pikasTech/agentrun/issues/219) 的 Final Response 重复与历史 assistant_message 整段重放：PR #314 自动上线后的真实 Artificer run `run_d2cd5c7b9c4149a28dd6e8403c77fa01` 已由有界单事件 CLI 确认 seq=22/27/36 是三个 `completed-agent-message`（itemId A/B/C），seq=38/39/40 却又以相同 A/B/C 发出 `agent-message-delta-progress` 的 terminal `progressFlush`，seq=42 才是指向 C 的无正文 final seal；根因是 completed item 未从 delta progress state 精确封口，`finalize()` 再次 flush，并非 Kafka/SSE 或文本重复。按 itemId 修复 AgentRun/Codex backend progress/completion 生命周期，保留不同 itemId 同文消息语义并确保无正文 seal 只作 authority control；禁止 HWLAB/Workbench 文本去重、tail 合并或 Kafka/SSE 补洞，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.3_Task_Report.md)。

#### R5.3.1 [in_progress]

继续解决 [AgentRun #219](https://github.com/pikasTech/agentrun/issues/219)：真实验收 run_3bd02d10ee534b8ca29176f15a893555 的 seq 136/137 是同一 itemId、完成前的累计 agent-message-delta-progress，seq 138 才是 durable completed body；三者都编码为 assistant_message，导致 timeline 显示三条近似 final response。将 live delta/progress、durable completed body、bodyless final seal 与 terminal status 在权威 event contract 中明确区分，同时保留实时可见性和 #316 的 late-replay/itemId/seal 修复；禁止 HWLAB/Workbench 文本去重、tail merge 或 Kafka/SSE 补洞，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.3.1_Task_Report.md)。

### R5.4 [completed]

解决 [AgentRun #319](https://github.com/pikasTech/agentrun/issues/319)：Artificer 既有 session send 在 new-turn runner admission 的 kubectl get jobs 失败后，已写入 run_22008379b6ac48e188032c1091c0741b 与 pending command，却没有 runner-job-created/typed terminal，session 永久显示 waiting-runner。将 session new-turn 改为 durable、幂等、可恢复的 runner dispatch 合同；admission/Job 失败必须写前 fail closed 或原子终态化并释放 session identity，覆盖 Memory/PostgreSQL、K8s failure、并发与 restart；禁止复制 task/session、数据库修补、第二清理 authority 或人工 CI/CD，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.4_Task_Report.md)。

### R5.5 [in_progress]

解决 [AgentRun #322](https://github.com/pikasTech/agentrun/issues/322)：PR #321 自动发布并原位恢复旧 run/command 后，durable dispatcher 在正式 NC01/nc01-v02 manager 内以类型化 runner-kubernetes-observation-failed 重试并终态化，精确失败为 kubectl get jobs exit=1，Artificer backend 未建立。调查并修复 manager 的 Kubernetes identity/namespace/RBAC/kubectl transport 与 bounded redacted 诊断，保持 durable intent、typed terminal、session release 和 Kafka event 合同；禁止回退同步 HTTP kubectl、扩大容量、删 Runner、数据库修补、复制 task/session 或人工 CI/CD。自动发布后必须在同一 Artificer session 继续原只读哨兵报告并进入 backend turn，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.5_Task_Report.md)。

#### R5.5.1 [in_progress]

解决 [AgentRun #324](https://github.com/pikasTech/agentrun/issues/324)：同一 session 首次 run 已将 UniDesk bundle 物化到 session workspace，但新 Runner 续跑 cwd 回退为镜像内 AgentRun 源码；恢复 durable session workspace/resource binding、PVC mount 与 workdir，并让 session describe 有界披露绑定和 mismatch，禁止 clone、prompt cd、宿主路径 fallback、新 task/session 或人工 CI/CD，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R5.5.1_Task_Report.md)。