docs: specify agentrun rolling recovery architecture

2026-06-20 07:12:24 +00:00
parent daedcd5b21
commit d05b963064
5 changed files with 148 additions and 0 deletions
@@ -81,6 +81,85 @@ AgentRun核心负责把 HWLAB Agent 任务转化为可持久查询、可调度
 | PJ2026-01020102 | Runner执行 | 本规格 6.3 | runner register、claim、lease、poll、ack、append events 和 terminal status | Manager API、Runtime 装配、Backend Profile | Manager、HWLAB 接入、Queue 会话 |
 | PJ2026-01020103 | Durable事实 | 本规格 6.4 | Postgres 表、migration ledger、事务和重启后查询 | Manager API、平台运维数据库支撑 | 全部 AgentRun 查询和恢复 |
 | PJ2026-01020104 | 终态结果 | 本规格 6.5 | command/run 终态分离、result envelope、failureKind 和 event 分页 | Runner执行、Backend Profile | HWLAB 接入、客户端、HarnessRL |
+| PJ2026-01020105 | 控制面恢复 | 本规格 6.6 | manager boot/background reconciler、runner job observation 和 active command 收敛 | Durable事实、Kubernetes Job/Pod | HWLAB 接入、发布Lane、运维监控 |
+| PJ2026-01020106 | 终态Outbox | 本规格 6.7 | runner terminal fact 的幂等提交、重试和可恢复 artifact | Runner执行、Backend Profile | 控制面恢复、HWLAB 投影 |
+| PJ2026-01020107 | 清理安全 | 本规格 6.8 | cleanup、Job TTL、runner 上限与 active runner 保护 | 控制面恢复、发布Lane | 平台运维、运行面 GC |
+
+### 5.1 控制面恢复目标架构图
+
+```mermaid
+flowchart LR
+  Submit[HWLAB / CLI submit] --> API[agentrun-mgr REST]
+  API --> DB[(Postgres durable ledger)]
+  DB --> Run[run / command / event / lease]
+  DB --> RJ[runner_job identity]
+  RJ --> K8S[Kubernetes Job / Pod]
+  K8S --> Runner[agentrun-runner data plane]
+  Runner --> Outbox[terminal outbox / retry artifact]
+  Outbox --> API
+  API --> DB
+  Boot[manager boot/background reconciler] --> DB
+  Boot --> K8S
+  Boot --> Obs[observation facts]
+  Obs --> DB
+  DB --> Result[result / diagnosis API]
+```
+
+AgentRun核心的目标状态是控制面无状态、runner 数据面可独立运行、Postgres durable ledger 是执行事实 authority。`agentrun-mgr` 重启或滚动后只能从 DB active facts、runner job identity 和 Kubernetes Job/Pod observation 重新接管控制权；进程内内存、stdout tail、Kubernetes Job completed、人工 resubmit 或重新创建 runner job 都不能替代恢复控制权。
+
+### 5.2 runner 滚动数据流图
+
+```mermaid
+flowchart TD
+  CMD[durable command] --> Claim[runner claim + lease]
+  Claim --> Job[runner job record + Kubernetes Job]
+  Job --> Work[backend turn execution]
+  Work --> Events[best-effort progress events]
+  Work --> Terminal[command terminal fact]
+  Events --> Store[(durable ledger)]
+  Terminal --> Outbox[durable terminal outbox / retry]
+  Outbox --> Store
+  Store --> Reconcile[manager reconciler]
+  Reconcile --> Result[result / liveness / diagnosis]
+```
+
+progress event 可以 best-effort；command terminal、run terminal、final assistant response、failureKind 和可恢复 artifact 必须通过 durable commit 或可被 reconciler 找回的 outbox/artifact 进入 ledger。runner 不得因为 manager HTTP 短暂不可用而静默退出并丢失 terminal fact。
+
+### 5.3 manager rolling 关键时序图
+
+```mermaid
+sequenceDiagram
+  participant M1 as manager before rolling
+  participant DB as durable ledger
+  participant K8S as Kubernetes Job/Pod
+  participant R as runner
+  participant M2 as manager after rolling
+
+  M1->>DB: create run/command/runner_job
+  M1->>K8S: create runner Job
+  R->>M1: claim/heartbeat/events
+  M1--xR: rolling / temporarily unavailable
+  R->>R: continue backend work
+  R->>DB: terminal outbox artifact is durable or retryable
+  M2->>DB: scan active command + runner_job + lease
+  M2->>K8S: observe Job/Pod phase and metadata
+  M2->>DB: update observation / terminal report state
+  R->>M2: retry terminal report
+  M2->>DB: idempotent terminal commit
+```
+
+恢复时序要求 manager rolling 只造成短暂控制面不可用，不造成 runner job 删除、run 重建、command resubmit、terminal fact 丢失或 read-side 推断 completed。
+
+### 5.4 rolling failure matrix
+
+| 场景 | 权威输入 | 正确收敛 | 禁止替代 |
+| --- | --- | --- | --- |
+| manager down during claim | command pending/claimed、lease、runnerJob、Kubernetes Job phase | reconciler 重新观察 claim/lease/job 并恢复 runner 控制或写 blocker | 按 stale lease 直接判 runner lost |
+| manager down during backend turn | heartbeat、events、Job/Pod running、runner job record | 保留 active，继续观察，暴露 temporary diagnostic | 删除 Job 或人工 resubmit |
+| manager down during event append | event cursor、runner retry、Job/Pod running | progress 可降级，terminal 仍需 durable | 用 stdout tail 当正式 event stream |
+| manager down during terminal report | terminal outbox/artifact、commandId、attemptId、runnerId | 幂等 terminal commit 或不可恢复 blocker | 静默保持 running |
+| Job completed before terminal commit | Job/Pod phase、outbox/artifact、logs retention | reconciler 恢复 terminal fact 或写不可恢复 blocker | 把 Job completed 单独当 command completed |
+| cleanup/TTL race | DB terminal state、runnerJob observation、TTL config | terminal durable 后再清理可恢复证据 | 只按 Pod 列表或年龄清理 active runner |

 ## 6. 原子需求

@@ -135,3 +214,33 @@ file、sqlite、JSONL、内存对象或 Pod 本地目录只能用于自测试或
 AgentRun核心应分离 command terminal 与 run terminal，并以 result envelope、event cursor、terminal status 和 failureKind 提供可判定的执行结果。

 partial assistant 文本、stdout 存在、transport close、idle timeout 或日志尾部都不能单独升级为 `completed`。成功和失败都必须能通过 command record 与 command-scoped events 查询；run 级终态只用于 run cancel、runner 级不可恢复失败或明确 run terminal。
+
+### 6.6 AR-CORE-REQ-006 控制面恢复 Reconciler
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| AR-CORE-REQ-006 | 控制面恢复 | PJ2026-01020105 控制面恢复 | [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)、[运维监控](PJ2026-010605-observability-monitoring.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md) |
+
+AgentRun核心应提供 manager boot/background reconciler，从 Postgres active run/command/runnerJob/lease facts 扫描需要恢复控制的执行对象，并查询 Kubernetes Job/Pod observation 写回 durable observation facts。reconciler 至少应表达 runner job phase、lastK8sObservedAt、terminalReportState、lease health、recoverable blocker 和不可恢复 blocker，字段命名可等价但职责不得省略。
+
+stale lease 不能单独推断 runner lost。runner lost、still running、completed pending terminal report、terminal committed 和 unrecoverable blocker 必须由 heartbeat、Kubernetes phase、runner job identity、terminal report state 和受控时间窗口共同判定，并由 AgentRun 写侧收敛。HWLAB、Web、CLI、result renderer 和 Workbench GET 只能消费这些 durable facts 和 diagnostics。
+
+### 6.7 AR-CORE-REQ-007 runner terminal durable outbox
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| AR-CORE-REQ-007 | 终态Outbox | PJ2026-01020106 终态Outbox | [后端Profile](PJ2026-010204-backend-profile.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) |
+
+runner 对 command terminal、run terminal、final assistant response、failureKind、threadId/turnId 和 terminal artifact 摘要必须使用 durable outbox、retry-until-ack 或等价可恢复提交协议。manager HTTP 短暂不可用时，runner 可以延迟上报，但不能把 terminal fact 只保留在进程内内存或易丢 stdout 中。
+
+terminal 上报必须幂等。同一 `runId + commandId + attemptId + runnerId` 或等价稳定键重复上报时，应返回既有 terminal commit 或结构化冲突，不得创建重复 terminal event、重复 final response 或覆盖已 sealed 结果。若 runner 已退出且 terminal fact 无法从 outbox/artifact/Job logs 恢复，manager reconciler 必须写入明确不可恢复 blocker，不能静默停留 running。
+
+### 6.8 AR-CORE-REQ-008 cleanup/TTL/runner 上限安全
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| AR-CORE-REQ-008 | 清理安全 | PJ2026-01020107 清理安全 | [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[运维监控](PJ2026-010605-observability-monitoring.md) |
+
+AgentRun cleanup、Job TTL 和 runner 上限治理必须以 DB active facts 与 Kubernetes observation 双确认作为判断基础。默认 cleanup 不得杀 active runner；确需强制终止 active runner 时必须使用显式 force 语义，并写入原因、操作者、对象和 observed facts。
+
+Job TTL 和日志/termination metadata 保留窗口不得早于 terminal facts durable commit 所需的最低恢复窗口。runner 上限治理应优先清理 idle、terminal、expired 或不可恢复对象；不得只根据 Pod 列表、Job age、进程内计数或旧 lease 单字段清理 runner。
@@ -32,6 +32,8 @@

 HWLAB接入负责把 HWLAB Cloud API、Workbench、CLI、HWPOD 运行上下文和 AgentRun durable execution 合同连接起来，使 HWLAB 能以手动调度 API 完成 Code Agent canary，并逐步收敛到可续跑、可取消、可追踪、可映射结果的 AgentRun 执行路径。

+HWLAB接入不拥有 AgentRun run、command、runner job、lease 或 terminal status 的执行事实。HWLAB 只负责在 admission 阶段生成业务 session/turn/message/trace 标识和 AgentRun 委托请求，并在后续通过 AgentRun durable events/result/diagnosis API 消费执行事实，再交给 WorkbenchProjectionWriter/Finalizer 写入 HWLAB 用户态投影。manager rolling、runner stale、terminal report delayed 或不可恢复 blocker 都必须先在 AgentRun 写侧形成 durable facts 或 diagnostic，HWLAB 不得通过 GET、result polling、trace tail、Web reducer 或人工 resubmit 补造执行状态。
+
 ### 2.2 范围内

 - HWLAB 业务 dispatcher 创建 AgentRun run、command 和 runner job 的字段映射。
@@ -39,6 +41,7 @@ HWLAB接入负责把 HWLAB Cloud API、Workbench、CLI、HWPOD 运行上下文
 - HWLAB session/provider/profile、conversation、workspace、gitbundle、promptRefs、requiredSkills 和 toolCredentials 的接入口径。
 - HWLAB HWPOD/runtime 短期上下文通过 transientEnv 或 tool credential 进入 runner job 的边界。
 - AgentRun events、command result、terminal status、failureKind 和 result envelope 到 HWLAB trace/result 的映射。
+- AgentRun rolling/reconciler/outbox diagnostic 到 Workbench projection diagnostic 的接入边界。

 ### 2.3 范围外

@@ -60,6 +63,7 @@ HWLAB接入负责把 HWLAB Cloud API、Workbench、CLI、HWPOD 运行上下文
 | HWPOD runtime context | HWLAB dispatcher 为单次 runner job 提供的 owner-scoped 硬件运行上下文。 |
 | transientEnv | 单次 runner job 的短期 env 上下文，由 AgentRun 转为短期 Secret 投影并脱敏输出。 |
 | 自然语言单一路由 | `/v1/agent/chat` 中自然语言请求统一进入 AgentRun Code Agent turn，不由 Cloud API 做关键词分流或文本 fallback。 |
+| AgentRun durable facts | AgentRun 写侧持久化的 run、command、event、runner job、lease、terminal report state、result 和 diagnosis，是 HWLAB 接入消费执行状态的唯一上游事实。 |

 ## 4. 系统边界和接口

@@ -123,6 +127,8 @@ HWLAB接入应把 AgentRun result 和 events 投影为 HWLAB 自己的 Turn、Me

 HWLAB 接入消费 AgentRun events 时必须按 Workbench 唯一投影的 durable cursor 执行增量拉取。运行中进度以 `events?afterSeq=<lastSourceSeq>` 和 command/window 过滤后的 normalized facts 为主读源；AgentRun `/result` 只用于终态补全或后台归档，不得作为 running turn 的主读源，也不得因为 `/result` 慢或超时阻断 events projection、Workbench trace 进度或 projection state 推进。

+AgentRun manager rolling 或 runner terminal report delayed 时，HWLAB接入只能消费 AgentRun durable diagnosis、observation facts 和 terminalReportState，并把它们交给 Workbench projection diagnostic。若 AgentRun ledger 暂时 stale、runnerJob observation 尚未恢复或 terminal outbox 尚未提交，HWLAB 应输出 projecting/degraded/stalled/blocker 等可解释状态；不得在 dispatcher、compat wrapper、GET handler、CLI renderer、trace polling 或 Web reducer 中根据 Kubernetes Job phase、stdout、最后一条 event、elapsed timeout 或用户切换 session 推断 completed。
+
 同一次用户提交、steer 或 retry 应在 admission 时生成稳定 turnId、traceId、userMessageId 和 assistantMessageId。初发 UI 可以基于这些标识做 optimistic 展示；AgentRun events/result 到达后必须用同 ID 确认或更新对应 message/part/turn/trace，而不是创建另一条会话消息。页面刷新、session 切换、SSE 重连和 CLI inspect/result 都必须恢复同一组标识和同一语义结果。

 ### 6.4 AR-HWLAB-REQ-004 HWPOD Runtime Context
@@ -79,6 +79,7 @@ Terminal final response 是 Workbench 投影的 sealed 用户结果。Projection
 | result sync state | AgentRun `/result` 归档或终态补全的低优先级状态；它不得阻塞运行中 events projection。 |
 | sourceLatestSeq | finalizer 在本次或最近一次拉取中观察到的 AgentRun command 最新 sourceSeq，用于诊断投影 lag；它不得替代 lastSourceSeq 成为已提交事实。 |
 | projection diagnostic | 暴露 projection lag、blocker、lastProjectedSeq、sourceRunId、sourceCommandId、updatedAt 和恢复状态的可诊断字段。 |
+| AgentRun execution diagnostic | AgentRun durable ledger 对 runner job observation、stale lease、terminalReportState、reconciler backlog 和不可恢复 blocker 的诊断输出；Workbench 只能把它作为 projection diagnostic 输入，不拥有执行状态写权。 |
 | transport diagnostic | SSE、turn polling、trace hydration、result sync、realtime timeout 或浏览器网络层观察到的可见性诊断；它只能描述传输或读侧健康，不拥有 message text、finalResponse 或 terminal status 写权。 |
 | projection health | 对 projection diagnostic 的只读解释，状态至少区分 `projecting`、`caught-up`、`degraded` 和 `stalled`；它不推进 facts，也不得把 stale projecting 标为 caught-up。 |
 | TraceEventPage | 由 WorkbenchReadModel 返回的 trace 分页事实，必须按 `projectedSeq` 单调排序，并保持 `range.fromSeq <= range.toSeq`；空页用显式 empty range 表达，不生成非法区间。 |
@@ -298,6 +299,8 @@ WorkbenchProjectionFinalizer 应以 checkpoint 为驱动追平 AgentRun facts。

 Finalizer 不得伪造 terminal、不取消 AgentRun、不用日志尾部推断 completed，也不得让 GET route 临时同步执行 finalization。若 AgentRun 事实暂不可取或映射失败，finalizer 应写入 diagnostic blocker，保留 retry 所需 sourceRun/sourceCommand/checkpoint。

+AgentRun rolling recovery 的缺口必须显式落入 projection diagnostic。若 AgentRun durable ledger 缺 terminal fact、runnerJob observation 尚未恢复、lease stale 但 Kubernetes phase 未确认、terminalReportState 仍 pending/outbox-retrying，或 AgentRun result/diagnosis API 返回 unrecoverable blocker，Finalizer 应把这些上游事实归一化为 Workbench projectionStatus、projectionHealth、blocker、sourceRunId、sourceCommandId 和 nextRetryAt 等诊断字段。Finalizer 不得根据 Kubernetes Job completed、stdout tail、最后一个 AgentRun event、elapsed timeout、session summary 或 Web 当前页面状态补造 Workbench completed。
+
 Startup/resume authority 只属于 cloud-api boot/background scheduler。该 scheduler 启动后必须扫描 durable open checkpoint、`projectionStatus=projecting` 或等价 running/projecting turn，按 bounded concurrency、attempt、lastAttemptAt 和 backoff 推进；它只能调用同一 `WorkbenchProjectionFinalizer/Writer`，不得新增第二套 result polling、manager shortcut 或 GET repair。恢复任务失败时必须写入 `lastError/blocker` 和下一次 retry 所需 cursor，不能静默丢弃。

 Finalizer 的 cursor 必须以 command 和 checkpoint 为边界追平。对同一 run 的第二个及后续 command，finalizer 必须从该 command 自己的 checkpoint 或 command-scoped event/result window 继续，避免每次从 run head 扫描大量旧事件；当只能获得 run-level event page 时，也必须用 `sourceCommandId`、稳定幂等键和 source checkpoint 过滤旧 command 事件。result 先到、events 后到、terminal event 缺失但 command result terminal、source event 缺口或 sourceSeq 回退都必须进入 diagnostic/blocker 或补洞路径，不得在读侧修正。
@@ -366,6 +369,8 @@ Durable recovery 红灯必须覆盖长 run、多 command 和大量旧事件场

 fake-server Playwright 应使用目标 node/lane 的真实采集脱敏 fixture，覆盖 session 切换、刷新、SSE 断线重连、REST 补洞、trace 分页和 terminal final response。D601 v0.3 public origin web-probe 应验证不切 session、不刷新页面、fresh deep link 和多观察者场景都通过同一 read model 收敛。

+AgentRun rolling recovery 回归必须覆盖上游 stale ledger 与不可恢复 blocker 样本：manager rolling 后 AgentRun diagnosis 仍处于 pending observation 时，Workbench list/detail/messages/turn/trace 应一致展示 projecting/degraded/stalled diagnostic；terminal facts 后续提交后，同一 durable projection writer/finalizer 应自然推进 sealed final response。测试不得通过 GET read-through、Web reload、切换 session、result fallback 或 fake-server 后门把 pending 状态改成 completed。
+
 Sealed final response 回归必须构造 completed assistant 主正文已经展示后，`/v1/workbench/turns/{traceId}`、`/v1/workbench/traces/{traceId}/events`、SSE 或 realtime diagnostic 发生 timeout/500/gap/close 的样本，断言主消息正文、finalResponse、message status 和 turn terminal 保持 sealed 不变，诊断只出现在 trace detail、transport diagnostic、session health 或消息详情入口。回归还必须覆盖 trace detail 延迟返回、分页缺口和用户手动展开/折叠状态，确保 late update 不 remount 主消息卡片、不重置用户控制状态。

 0repair 验收必须先在 fake-server + Playwright 中形成红灯：fresh context 直达 session A、普通点击切到 session B、A 的 delayed detail/turn/trace/SSE 晚到、用户没有提交 B 的新消息时，B 的 URL、active tab、message card、composer 和 trace detail 不得出现 A 的 user/agent 文本、running 状态或 terminal trace。web-probe 必须连续截图观察提交前、running、中间态、terminal 和晚到事件；不得用 reload、切换 session、`sessionRepair`、`realignFreshSession`、localStorage 修改或 helper 自动点击修正页面后再判通过。
@@ -37,6 +37,7 @@ AgentRun发布Lane负责定义 AgentRun `v0.1` 在 G14 上的专用发布 lane
 - Env image reuse、digest-pinned image、artifact promotion 和 runner/backend work-ready image 要求。
 - AgentRun manager、runner、Postgres、SecretRef、provider profile、Queue/Session 和 backend real turn 在综合联调中的发布判定。
 - AgentRun CLI 在发布验收中的正式操作入口，包括 runs、commands、runner jobs、queue、sessions、provider profiles、backends、secrets 和 server lifecycle 命令。
+- manager rolling、runner terminal outbox、reconciler re-attach 和 HWLAB Workbench projection recovery 的 rolling/chaos 发布验收。

 ### 2.3 范围外

@@ -53,6 +54,7 @@ AgentRun发布Lane负责定义 AgentRun `v0.1` 在 G14 上的专用发布 lane
 | AgentRun CI | G14 上用于 AgentRun `v0.1` 构建、promotion 和 GitOps 更新的 Tekton pipeline。 |
 | env image | AgentRun runner/backend 的 work-ready 基础执行环境镜像。 |
 | real provider turn | 通过真实 Codex app-server stdio backend 和真实 provider SecretRef 完成的一次 Code Agent turn。 |
+| rolling recovery canary | 在真实 runner 执行期间滚动 HWLAB cloud-api 或 AgentRun manager，并证明同一 run/command/runnerJob 被恢复控制且最终投影到 Workbench 的发布验收切片。 |

 ## 4. 系统边界和接口

@@ -75,6 +77,7 @@ AgentRun发布Lane负责定义 AgentRun `v0.1` 在 G14 上的专用发布 lane
 | PJ2026-0106010502 | EnvImage | 本规格 6.2 | env image identity、digest-pinned image、work-ready 工具和 promotion | Source commit、registry、Containerfile | Runtime装配、runner job |
 | PJ2026-0106010503 | CLI验收 | 本规格 6.3 | AgentRun CLI JSON、短返回、redaction 和正式命令入口 | AgentRun REST API | HWLAB 接入、队列会话 |
 | PJ2026-0106010504 | 真实联调 | 本规格 6.4 | real provider turn、Postgres durable facts、SecretRef 和 terminal status | AgentRun核心、后端Profile | 发布判定 |
+| PJ2026-0106010505 | Rolling验收 | 本规格 6.5 | manager/cloud-api rolling、runner 不中断、reconciler re-attach 和 Workbench projection recovery | AgentRun核心、HWLAB接入、Workbench唯一投影 | 发布判定、运维监控 |

 ## 6. 原子需求

@@ -117,3 +120,13 @@ CLI 默认输出 JSON，stdout 不得为空伪成功，长时间模型 turn 必
 AgentRun `v0.1` 综合联调必须在真实 `agentrun-v01` 运行面完成，使用真实 Postgres、真实 Kubernetes SecretRef、真实 manager/runner/backend、真实 RuntimeAssembly 和至少一个真实 Code Agent provider turn。

 mock backend、fake provider、source-only、dry-run、缺 provider credential 时的 skip、只读 health 成功或没有真实 command terminal status 的运行面状态，都不能作为 AgentRun 发布通过证据。涉及 profile 的变更还必须覆盖相关 backendProfile 的真实切换与隔离。
+
+### 6.5 AR-RELEASE-REQ-005 rolling/chaos 发布验收
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| AR-RELEASE-REQ-005 | Rolling验收 | PJ2026-0106010505 Rolling验收 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[运维监控](PJ2026-010605-observability-monitoring.md) |
+
+AgentRun `v0.1` 发布验收应包含 rolling recovery canary。验收在 D601 v0.3 HWLAB 用户入口或等价受控 CLI 发起长程 Code Agent session，记录 `sessionId`、`traceId`、`runId`、`commandId`、`runnerJobId` 和 Kubernetes `jobName`；runner 正在执行时滚动 HWLAB cloud-api，runner 继续执行时滚动 AgentRun manager。滚动结束后，同一 run/command/runnerJob 必须被 manager reconciler 恢复控制并进入 Workbench projection，不重建 run、不人工 resubmit、不切 session repair。
+
+rolling recovery canary 的通过证据至少包含：runner Job 未被删除或重建、terminal fact 通过 AgentRun durable ledger/outbox/reconciler 进入 DB、Workbench list/detail/messages/turn/trace 对同一 turn 状态一致、sealed final response 不被后续 diagnostic 覆盖，以及 CLI/web-probe/trace evidence 可关联同一运行对象。滚动期间允许短暂服务不可用或 diagnostic，但不得出现任务丢失、重复消息、session 跳转、状态回退或读侧 repair 通过。
@@ -41,6 +41,7 @@
 - OpenTelemetry Collector、trace backend、span 语义、trace context 传播和 trace 查询入口。
 - Web/API/AgentRun/HWPOD/Harness/用户管理等服务的运行面健康、资源状态、公开入口健康和用户可感知性能观测。
 - 发布后 runtime readiness、resource usage、error rate、queue depth、target availability 和 alert 状态摘要。
+- AgentRun rolling recovery 的 active runner、stale lease、terminal report retry、reconciler backlog、projection lag 和 Job TTL cleanup 观测。
 - 监控和 trace 数据的受控查询、低噪声摘要、失败归因和敏感输出约束。

 ### 2.3 范围外
@@ -63,6 +64,7 @@
 | trace context | W3C `traceparent`/`baggage` 等跨进程传播上下文；业务 `traceId/sessionId/runId/turnId` 只能作为 span attribute，不能替代标准 trace context。 |
 | 用户可感知性能 | 用户在 Web、CLI 或 API 入口中直接感受到的等待时间、加载时间、首个可读内容出现时间和完整可用状态。 |
 | YAML-first 运维监控 | Prometheus scrape、rule、summary 和 target 归属先进入 UniDesk YAML，再通过受控 CLI 渲染和验证的运维形态。 |
+| rolling recovery signal | 用于判断 manager/cloud-api rolling 后同一 run/command/runnerJob 是否恢复控制权的低基数 metrics、span attribute 和 CLI 摘要字段。 |
 | scrape target | Prometheus 抓取 metrics 的目标服务、path 和 label 集合。 |
 | metrics endpoint | 服务暴露运行状态、资源状态和业务健康指标的 HTTP 端点。 |
 | alert rule | 对 metrics 表达告警条件的规则，具体阈值来自配置。 |
@@ -90,6 +92,7 @@
 | PJ2026-01060504 | 边界约束 | 本规格 6.4 | 监控与业务通过、长证据、敏感输出的边界 | 全部 L1 | 用户反馈和排障 |
 | PJ2026-01060505 | Workbench性能 | [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) | Web 工作台用户可感知性能、RUM、AgentRun event visible latency 和 Prometheus 指标口径 | Web工作台、Agent编排、API契约 | 平台运维、客户端和性能回归调查 |
 | PJ2026-01060506 | Metrics接入 | 本规格 6.6 | metrics endpoint、scrape target 和 label 口径 | 各 L1 服务健康指标 | Prometheus 查询 |
+| PJ2026-01060507 | Rolling恢复观测 | 本规格 6.7 | active runner、reconciler backlog、terminal retry、projection lag 和不可恢复 blocker 的查询口径 | AgentRun核心、HWLAB接入、Workbench唯一投影、发布Lane | rolling 发布判定、故障收口 |

 ## 6. 原子需求

@@ -242,6 +245,18 @@ Workbench 性能监控只记录低基数指标、阶段耗时、状态分类和

 各 L1 负责定义自身服务健康指标含义；平台运维负责通过 YAML-first UniDesk ops 统一接入、命名、label 和可查询状态。metrics 缺失应暴露为监控缺口，不得用日志 grep、一次性 curl、手工 `kubectl apply` 或人工截图替代长期监控。

+### 6.7 OPS-MON-REQ-007 Rolling 恢复观测
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-MON-REQ-007 | Rolling恢复 | PJ2026-01060507 Rolling恢复观测 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) |
+
+运维监控应为 AgentRun/HWLAB rolling recovery 提供可查询的低基数 metrics、trace span 和受控 CLI 摘要。最小观测对象包括 active runner 数、runner job observation phase、stale lease 数、terminal report retry/outbox backlog、manager reconciler backlog、reconciler last success/error、projection lag、projection blocker 数、Job TTL cleanup 数和不可恢复 blocker 数。
+
+rolling recovery 相关 span 应能用 OTel trace id/request id 关联 `sessionId`、`traceId`、`runId`、`commandId`、`runnerJobId` 和 `jobName` 的 redacted attribute。高基数业务 ID 只能作为 trace/span attribute 或 CLI 单次查询参数，不进入 Prometheus label；prompt、assistant 正文、tool 参数、stdout/stderr、Secret、完整 token、完整 DSN 和 provider payload 不得进入默认 metrics、span 或 issue closeout。
+
+发布/rollout 前后的受控 CLI 摘要应能回答：仍在运行的 runner 数、已恢复控制权数量、terminal report retry 数、projection lag 最大值、不可恢复 blocker 数和最近一次 reconciler 错误。该摘要只用于定位和发布判定，不替代 P6 原入口 rolling/chaos 验收，也不能把可观测性 green 当作业务任务完成。
+
 ## 7. 过程控制

 本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。