docs(agentrun): 收口重试与资源包可靠性

.agents/skills/unidesk-code-queue/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: unidesk-code-queue
-description: UniDesk AgentRun-backed Code Queue CLI — Skill(cli-spec)。legacy `codex` 子命令只保留历史只读和残留停止；新任务提交、Aipod/Artificer 派单、session follow-up、events/logs/result、ack/cancel、dispatch、run/command/runner 状态 drill-down 和 HWLAB Code Agent/CaseRun follow-up 必须使用 `agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|send` 资源原语。用户提到 codex、Code Queue、submit、send、resume、tasks、unread、code-queue、aipod、Artificer、HWLAB Code Agent 时使用。
+description: UniDesk AgentRun-backed Code Queue CLI — Skill(cli-spec)。legacy `codex` 子命令只保留历史只读和残留停止；新任务提交、Aipod/Artificer 派单、session follow-up、events/logs/result、attempts/retry、ack/cancel、dispatch、run/command/runner 状态 drill-down 和 HWLAB Code Agent/CaseRun follow-up 必须使用 `agentrun get|describe|events|logs|result|retry|ack|cancel|dispatch|create|apply|send` 资源原语。用户提到 codex、Code Queue、submit、send、resume、retry、tasks、unread、code-queue、aipod、Artificer、HWLAB Code Agent 时使用。
 ---
 
 # UniDesk Code Queue / AgentRun CLI
 
-新任务、Aipod/Artificer 派单、session follow-up、events/logs/result、ack/cancel、dispatch 和 run/command/runner drill-down 走 AgentRun 资源原语。legacy `codex` 只保留历史只读、未读积压和残留任务停止。
+新任务、Aipod/Artificer 派单、session follow-up、events/logs/result、attempts/retry、ack/cancel、dispatch 和 run/command/runner drill-down 走 AgentRun 资源原语。legacy `codex` 只保留历史只读、未读积压和残留任务停止。
 
 ## 高频入口
 
@@ -15,6 +15,8 @@ bun scripts/cli.ts agentrun describe task <task>
 bun scripts/cli.ts agentrun events <task> --limit 80
 bun scripts/cli.ts agentrun logs <task> --tail 120
 bun scripts/cli.ts agentrun result <task>
+bun scripts/cli.ts agentrun get attempts --task <taskId>
+bun scripts/cli.ts agentrun retry task/<taskId> --idempotency-key <key> --reason <text> --dry-run
 bun scripts/cli.ts agentrun send <session> --prompt-stdin
 ```
 
@@ -27,6 +29,8 @@ AipodSpec/Artificer、task manifest 和 queue 渐进披露见 [references/resour
 - 新写入口不要用 `codex submit/steer/resume`；这些 legacy mutation 已冻结。
 - 默认输出保持低噪声表格/摘要；机器消费显式 `-o json|yaml` 或 `--raw`。
 - Session follow-up 使用 `agentrun send`，由服务端决定内部 steer vs turn。
+- 终态失败重试只使用 `agentrun retry task/<taskId>`：保持同一 task，新增不可变 attempt；先用 `--dry-run` 完成服务端全校验，再以同一幂等键执行真实重试。
+- retry 只接受 Queue 已处于 `failed` 或 `blocked`；`completed`、`cancelled` 和其他状态必须 fail closed。不得复制 task、重置 task、引入本地 scheduler/backoff/judge 或直接创建 runner Job 来模拟重试。
 - HWLAB Code Agent/CaseRun follow-up 也优先落到 AgentRun resource primitive，不绕过队列状态。
 
 ## 何时读取 reference

.agents/skills/unidesk-code-queue/references/resources.md

@@ -1,10 +1,21 @@
-# AgentRun Resources
+# AgentRun 资源原语
 
-New Code Queue work uses AgentRun resource primitives:
+新 Code Queue 工作统一使用 AgentRun 资源原语：
 
-- `agentrun create|apply` for task/AipodSpec manifests.
-- `agentrun get|describe` for bounded list/detail reads.
-- `agentrun events|logs|result` for progressive disclosure.
-- `agentrun dispatch|ack|cancel` for lifecycle control.
+- `agentrun create|apply`：创建 task 或应用 AipodSpec manifest；
+- `agentrun get|describe`：有界读取列表和详情；
+- `agentrun events|logs|result`：渐进披露运行证据；
+- `agentrun get attempts --task <taskId>`：读取同一 task 的不可变 attempt 历史；
+- `agentrun retry task/<taskId> --idempotency-key <key> --reason <text> [--dry-run]`：对终态失败 task 创建下一次 attempt；
+- `agentrun dispatch|ack|cancel`：控制生命周期。
 
-Do not add new mutation paths under legacy `codex`.
+retry 必须遵守以下边界：
+
+- task identity 不变，每次执行使用新的 attempt、run、command 和 runner Job identity；
+- 同一幂等键返回同一 retry 结果，不重复创建 attempt；
+- 只允许 Queue 已处于 `failed` 或 `blocked`，其他终态与非终态 fail closed；
+- `--dry-run` 由服务端完成与真实 retry 相同的校验，但零写入；
+- retry 不主动刷新 Core 终态。若 Queue 摘要仍是非终态，先通过正式 `get task` 或 `get attempts` 刷新权威状态，再重试；
+- 禁止复制或重置 task，禁止在 UniDesk 增加 scheduler、backoff、judge、projector 或直接 runner 编排。
+
+不要在 legacy `codex` 下增加新的 mutation 路径。